Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
The way that our docs are currently structured, it can be hard for some of our users to use. It is not very straightforward or easy to find where certain docs are. One example of a suggestion, all the actual docs or the place that many people would go straight to is in the "Reference" section, but it might be confusing since "Reference" sections can mean citations in webpages. Another suggestion was to bring back the one-page docs in order for faster lookup through CTRL-F.
These two points are just a couple of places that we can start at for restructuring and improving our docs. Currently, our docs is one of the main pain points of many of our users and we should try to make it as easy and extensive as possible.
This will probably be a long running issue, I'm just opening this to keep track of ideas and work that I will do to improve our docs.
I agree that we can do a bit of restructuring. A lot of the current layout was influenced by how other OSS projects structure their docs. For example, the k8s documentation site:
Uses the following L2 Nav labels:
Our docs, as of Jan 21 have:
I'm not sure what the new layout should be, but maybe a restructuring and separation?
Maybe instead of all these categories being under the header of "Docs", we can split it out to