Consolidate and update documentation / information

[tobias-tengler]

In my opinion the biggest problem this project has at the moment is outdated documentation, lack thereof and scattered/outdated information.

I've noticed this recently with some colleagues, who were trying out HotChocolate for the first time. They started from the GitHub page and followed the examples in the READMEs. Those were severely outdated and sometimes even contained errors. Consulting the documentation didn't help either, since it was scattered between versions and sometimes there were also errors. The slack channel turned out to be helpful, but as a developer you have this expectation of a good software tool being well documented. If you can't get up and running, without consulting a "group-chat" - that's bad and hurts the legitimacy of the project.

In order to improve the experience of new users, the following should happen in my opinion:

• Extensively document all Software Tools on the website.
• XML documentation of the C# code would probably also be really helpful, but having a good documentation on the website should suffice for the moment.
• Move scattered documents like ErrorCodes.md in the documentation.
• Make the ChilliCream documentation the single source of truth for documentation. No more code examples in scattered READMEs that tend to go out-of-date. Only one README at the project level with a quick description of the individual projects and links to their documentation.
• Remove the ROADMAP file from the project and only link to the GitHub Roadmap.
• Remove the examples directory and link to the example repositories from the documentation (only of course, if they are up-to-date).

I think after the release of 11.2.0 would be a good time to start tackling these issues. If we nail this HotChocolate will be the best .NET GraphQL implementation, not only feature and performance wise.

If you have other thoughts or more ideas towards a better and consolidated documentation, please share your opinion!

[tobias-tengler]

Maybe we could create an issue, where we track parts of the software that is currently undocumented. We could label it as "Help wanted" and pin it.
Every now and then there are people making documentation PRs with stuff they figured out via trial and error. If we make the need for help with documentation more visible, maybe there are more people that will chime in and fill in some blank spots!
I know balancing documentation and new features is hard, with such a relatively small team of maintainers. :)

[benherronscope]

We are currently prototyping HotChocolate to replace GraphQL.NET and your entirely correct with everything you have written.

Documentation is causing the most headaches and confusion for us so far.

I would rank GreenDonut higher then StrawberryShake for us as it's absolutely critical to actually getting data out of HotChocolate and it's documentation and real world examples are severely lacking.

I've wasted countless hours following links trying to work out how something should be done, which end up no where because the projects have been merged and upgraded and code moved.

XML Documentation of the C# code is also something that would be really appreciated.

When i have got things going it's worked well, but getting to that point is extremely frustrating.

[tobias-tengler]

There are now other issues addressing this, namely #4209.