There are lots of issues with ASP.NET Core documentation so I will highlight few.
1. The structure:
_Why do we need two tutorials for every project type?!!_
Here's one at Tutorials > Razor Pages
Here's one at Web Apps > Razor Pages > Tutorial
My problem is it forces us to follow the sample app they are building and not give us the quick docs and info we want.
You guys seriously need to learn from Django how to build a well structured documentation. Amazing that a non-profit builds a better documentation than a billion dollar company. Is it because you are too focused on adding new features that you forgot how important docs are? Or is it because you don't have enough (and competent) people who can design and write clear documentation?
2. Search Engine Optimization
The docs site sucks at SEO. Even when I type right keywords it never shows me the correct page in the docs. Never. This might be the direct consequence of horrible structure and relying on tutorial style docs. Every time I have to read through pages and pages to get to the real thing. Ditch the tutorial style docs and this will be a lot better.
Please take a look at Django docs and learn how to structure documentations. Your current docs may be good enough for people with experience in ASP.NET who work in a enterprise environment where they have seniors advising them, but it is absolutely unacceptable (not to mention, frustrating) for people new to the ASP.NET Core.
Seriously, learn from Django docs
Software versions
Check the .NET target framework(s) being used, and include the version number(s).
[ ] .NET Core
[x] .NET 5.0 or later
[ ] .NET Framework
[ ] .NET Standard
If using the .NET Core SDK, include dotnet --info output. If using .NET Framework without the .NET Core SDK, include info from Visual Studio's Help > About Microsoft Visual Studio dialog.
dotnet --info output or About VS info
```console
```
Rick-Anderson
commented
3 years ago
There are lots of issues with ASP.NET Core documentation so I will highlight few.
1. The structure:
_Why do we need two tutorials for every project type?!!_
Here's one at Tutorials > Razor Pages
Here's one at Web Apps > Razor Pages > Tutorial
My problem is it forces us to follow the sample app they are building and not give us the quick docs and info we want.
You guys seriously need to learn from Django how to build a well structured documentation. Amazing that a non-profit builds a better documentation than a billion dollar company. Is it because you are too focused on adding new features that you forgot how important docs are? Or is it because you don't have enough (and competent) people who can design and write clear documentation?
2. Search Engine Optimization
The docs site sucks at SEO. Even when I type right keywords it never shows me the correct page in the docs. Never. This might be the direct consequence of horrible structure and relying on tutorial style docs. Every time I have to read through pages and pages to get to the real thing. Ditch the tutorial style docs and this will be a lot better.
Please take a look at Django docs and learn how to structure documentations. Your current docs may be good enough for people with experience in ASP.NET who work in a enterprise environment where they have seniors advising them, but it is absolutely unacceptable (not to mention, frustrating) for people new to the ASP.NET Core.
Seriously, learn from Django docs
Software versions
Check the .NET target framework(s) being used, and include the version number(s).
If using the .NET Core SDK, include
dotnet --infooutput. If using .NET Framework without the .NET Core SDK, include info from Visual Studio's Help > About Microsoft Visual Studio dialog.dotnet --info output or About VS info
```console