Why is the documentation so bad?

[kasajian]

It's only a problem with Microsoft components.

I see a component in NuGet whose name looks interesting. I click on Project Site and I am immediately taken to the site for the project that produces the component, which explains what it is, etc.

But not with Microsoft components. Here's a simple example. I see a component in NuGet called "System.Threading.Tasks.Extensions". I click on Project Site. It takes me to a generic docs site, the main page that has nothing to do with System.Threading.Tasks.Extensions. If I then search for System.Threading.Tasks.Extensions, I got lots of hits, none of which are for System.Threading.Tasks.Extensions, but System.Threading.Tasks instead.

I do the search again, this time putting the component name in quotes, prepending a plus sign to indicate that I don't want to see any pages unless the exact name appears: +"System.Threading.Tasks.Extensions"

Now I am given a page that is about another component, value.types, that says I need System.Threading.Tasks.Extensions in order to use it.

Googling or Binging "System.Threading.Tasks.Extensions" doesn't do anything either.

Now, wouldn't it be better if System.Threading.Tasks.Extensions had a documentation page somewhere similar to MSDN, and if one does not exist, actually indicate it does not exist. If there's not docs, telling the user there's not docs is actually quite valuable. The user can stop looking for docs, and may be go elsewhere such as stackoverflow, forums or decide to look through the source.

There's a reason why there's a "project site" link on nuget.org. It's supposed to take you to the specific page for that component. It would be useful if that's what it did rather than sending you to an entire Docs site where you have to now search for the phrase.

[danmoseley]

@terrajobst

[karelz]

cc @mairaw if we have any pages we can link to cc @leecow @ericstj @weshaggard - where do we fill the docs? During publishing I assume. And we can change it for existing packages (@ericstj pointed me to the instructions recently AFAIK)

[mairaw]

I'm not aware of any pages we can link to that already exist. @rpetrusha do you know?

[svick]

I think the main problem here is that System.Threading.Tasks.Extensions is a package, but the API reference is organized by namespace. It would be nice if each package had its own page in the documentation, where the Project Link on NuGet could lead.

Another issue is that the API reference has no documentation for System.Threading.Tasks.ValueTask<T> (currently the only reason why that package exists).

As a short term fix, https://docs.microsoft.com/dotnet/articles/csharp/whats-new/csharp-7#generalized-async-return-types might be the best URL to link from that package. But all the other packages have the same issue too (just usually less pronounced, because their names are clearer or correspond to namespaces).

[krwq]

Should we perhaps simply add a README page for each library (under src/<library>/README.md) and add few samples per project + links to MSDN? Also link to that file in the nuget packages

[kasajian]

@krwq I think anything is better than what we have now, and I really do think your proposal is good. I think that if you even just point to a wiki page, then you'll have someone in the community fill in whatever information they happen to have.

[karelz]

I like @krwq's idea -- we need an easy-to-find place (with stable URL we can link from NuGet packages) that folks are not afraid to contribute to (both internal and external contributors). I don't think that CoreFX repo is the right place though -- @mairaw can you please guide us where to set up such docs? Would it be best in docs repo? Could we get some help from docs team with vetting the write ups, etc.?

BTW: We might still want to create README.md per library (as @krwq suggests) and put there link to this 'blessed' place where the docs live.

[kasajian]

Maybe there is a single service that can be used such that, based on the query in the URL, it will go to a page for that particular NuGet component. Or, maybe, the service can use the originating web-page to determine which component this is for. Anyway, once there, there can be a page that's both official docs, and community docs. That means that, from the get-go, every component will at a minimum have a community-page.

For instance, someone from the .NET Foundation / Core, etc. publishes to NuGet. For the Project Site, they specify some specific URL. Once published, if a user clicks on that link, they're sent to a doc page. The doc page may not have anything in it yet. but there's a community page link at the bottom (which also may not have anything in it), but people can at least start posting samples to help others.

[svick]

@kasajian I don't see any reason to have separate official and community docs. Whatever decision is made about where package documentation should be, it should be both official and accepting community contributions, just like almost everything related to .Net Core, including documentation, already is.

[krwq]

@svick fair point, I find README pages easiest to find and contribute. Usually any docs which are not close to a source code are quite outdated mostly because it is not obvious where do you change it. Whatever we choose it should be obvious how to contribute

[danmoseley]

Good feedback but no activity here in some time. I will close this. New suggestions are welcome in a new issue.

[kasajian]

I don't want to sound like I'm questioning the decision to close it, because I'm not. But I am curious what's the rationale for it. Is it because it's out of scope for this project? Is there no interest in ensuring that the nuget packages point to actual documentation? Seems like the Microsoft delivered nuget packages are the worst. This is just not a thing in other environments such as npm. The problem is pretty bad.

I got bitten by this again just yesterday. Please hear me out. I thought to myself, i wonder what "Analyzers" are out there, so within Visual Studio's NuGet search I looked at the list. I saw one called: Microsoft.CodeAnalysis.VersionCheckAnalyzer the description is "Microsoft.CodeAnalysis Version Check Analyzer" which doesn't add any value. the project URL points to: https://github.com/dotnet/roslyn-analyzers there's no mention of "VersionCheckAnalyzer", however you spell it. nada So i search the repository and found the source code within I found an XML that hints that this has something to do with version mismatch.

Doing a Google search on "VersionCheckAnalyzer" only points you back to NuGet. However, the it's got almost 5M downloads.

This is not an unusual experience. It seems pretty important to me -- but seems like it's not very important to Microsoft, and I really don't understand why.

[danmoseley]

@carlossanlop @ericstj do you know any history here , about nuget packages pointing to docs?

[carlossanlop]

The project URL for NuGet packages is specified in the <projectURL> xml tag of the *.nuspec file. It should be edited when the NuGet package is generated.

We could have a file with links the official Documentation to each assembly or namespace, and when the NuGet packages are generated, find their URL in that file.

@ericstj @joperezr @safern @ViktorHofer know more than me about this.

[carlossanlop]

I learned this by looking at the only *.nuspec file I have modified myself, which we use to generate the NuGet package we then consume internally to add intellisense when we build.

Coincidentally, the default URL there is also https://dot.net.

[joperezr]

Thanks for the feedback @kasajian. I think the main point in here is that you would like to have that our packages' Project Site link take you back to the repo that generates them right? I think that is fair and you are right that not all of our existing packages do that, for example, System.Text.Json does take you to github.com/dotnet/corefx, but System.Threading.Tasks.Extensions take you to https://dot.net/. The reason for this inconsistency is that in past releases (before .NET Core 3.0) we used to point all of those to https://dot.net/ and we changed it for our .NET Core 3.0 release to instead point to the actual repository that generated them, but some of the packages (like System.Threading.Tasks.Extensions) don't get build any longer in 3.x, which is why some of our old packages will still be pointing to https://dot.net/.

All that said, as you probably saw with the Analyzers package, looking into the repo that generates the package is not the best place to find documentation for it, and the reason for that is that we keep another repository with all of the API documentation https://github.com/dotnet/dotnet-api-docs/ from most of our repos. This docs repo will populate the content of our official documentation site: https://docs.microsoft.com/en-us/dotnet/csharp/ which is where I would encourage you to go and look for any documentation related to any API you were trying to consume from our packages. Would it make sense to change the project site to instead point to docs.microsoft.com in your opinion? Do you think that would help getting to the docs of a specific API you are interested faster?

[kasajian]

You're right that I haven't proposed what it should do. I just think if three's a link on a page for a particular nuget package, that link should go to someplace for that nuget package. If not, that nuget package should be listed on the page you clicked on. Going to https://dot.net/ isn't enough.

I feel like the solution should be obvious because every other nuget package that I've seen, other than the ones from Microsoft, seem to do it right.

Ideally, there would be a unique URL for each NuGet package that leads you to a page that describes what the package is.

[joperezr]

The likely reason why this is not a big issue for other NuGet packages that you've seen, is because in most other cases, there is a 1:1 mapping between repo and NuGet package, so it is easy to have the project site be the repo where the package is built and the main readme can just describe the contents of that package. In our repo (dotnet/runtime repo) we build around 216 different nuget packages for every build so we obviously can't really include the description of all of these in our Readme 😆. What we are currently doing for our vNext is to again point to the root of the runtime repo, but as you noted it won't really be taking you directly to the docs of that package. If we believe that it would be a better user experience to instead point to docs.microsoft.com/en-us/dotnet/ then we can totally change it to be that, but I'm not sure if that would fix the issue here. Perhaps the way to fix this is to create a Readme.md file for every one of those nugetpackages that we produce in our repo, and have the project site link to point to that? That would mostly fix the issue, but the problem I see here is that this wouldn't be very future proof, as we move files around our repo very often, and this link might get broken (this is why other nuget packages usually just link to the repo root, which is unlikely to change, and just add the docs on the root's readme)

[svick]

@joperezr

the problem I see here is that this wouldn't be very future proof, as we move files around our repo very often, and this link might get broken

If you linked to a specific page for that package on docs.microsoft.dom, that wouldn't be a problem. Even if that site was reorganized, docs have the ability to set up redirects.

[joperezr]

That is totally true for docs.microsoft.com, I has refering more to the case where we pointed back to a Readme.md on the repo as that was the example I gave for most NuGet packages.

[dotnet-policy-service[bot]]

Due to lack of recent activity, this issue has been marked as a candidate for backlog cleanup. It will be closed if no further activity occurs within 14 more days. Any new comment (by anyone, not necessarily the author) will undo this process.

This process is part of our issue cleanup automation.

[dotnet-policy-service[bot]]

This issue will now be closed since it had been marked no-recent-activity but received no further activity in the past 14 days. It is still possible to reopen or comment on the issue, but please note that the issue will be locked if it remains inactive for another 30 days.