Make getting started more obvious when reading docs

[ajcvickers]

We have had lots of great conversations over the last couple of years on improving doc layout. I don't want to forget all that, but this is something we could potentially do that is low cost and will help people getting started.

I have been reading Cosmos docs, and I noticed this structure:

That is, at the top level there are "Quickstarts" "Tutorials". These break out for the potential dimensions--in Cosmos case, the platforms/languages. The tutorials are then about building different kinds of applications.

For us, I think it would be:

• Quickstarts
  • Use EF Core with Azure Cosmos DB
  • Use EF Core with Azure SQL
  • Use EF Core with SQL Server on-premise
  • Use EF Core with PostgreSQL
  • Use EF Core with SQLite
  • Use EF Core with MongoDB
  • Use EF Core with MySql
  • Use EF Core with Oracle
• Tutorials
  • Build a console application with EF Core
  • Build an ASP.NET Core minimal API with EF Core
  • Build an ASP.NET Core Blazor application with EF Core
  • Build a Windows Forms application with EF Core
  • Build a MAUI application for EF Core
  • Build a WPF application with EF Core
  • Use EF Core in Jupyter Notebooks

[roji]

I love the direction and trying to make this all better - here are some thoughts.

I'm not sure a full quickstart page for each databases makes sense.. In the Cosmos case, obviously a different language warrants a completely different code sample (everything is different), but a simple quickstart for EF will like differ by only a single line across providers - UseSqlServer vs. UseNpgsql (of course as you get deeper there are many other differences, but probably not at the quickstart level).

Maybe it's enough to just use tabs here? i.e. in the "build a console application", "build an ASP.NET Core ...", we could have a tab for each provider where we show the code to configure the provider? This would also allow us to integrate all providers into all tutorial pages (and avoid an explosion of pages where we need to show console for SQL Server, for Cosmos...).

Another note is to think about the relationship between the above and the ASP.NET tutorials (e.g. this).

[ajcvickers]

In the Cosmos case, obviously a different language warrants a completely different code sample (everything is different), but a simple quickstart for EF will like differ by only a single line across providers - UseSqlServer vs. UseNpgsql (of course as you get deeper there are many other differences, but probably not at the quickstart level).

This is true, but the point here is to draw people in by letting them see something that they connect with without clicking into docs to get there. So, the point is to make "Cosmos with EF Core" a top-level item that people will see.

"build an ASP.NET Core ..."

These will be a link to the existing ASP.NET tutorial. For the tutorials we own, we can add tabs.

[roji]

This is true, but the point here is to draw people in by letting them see something that they connect with without clicking into docs to get there.

Right, from a "marketing" point of view I can see that.

These will be a link to the existing ASP.NET tutorial. For the tutorials we own, we can add tabs.

I guess I'm wondering more on the precise line between "EF tutorials including web" (living in our docs) and "Web tutorials including EF" (living in ASP.NET's). But anyway, not important.