Documentation overview page #357
Conversation
Two things were done in this patch: 1. There is only one Learn page which all learning material on there. It used to be the case that each project had (or didn't have) a Learn item in the navigation bar. In some cases the item in the navigation bar was called Manual which broke the consistency of the website and most importantly the expectations of the visitor. 2. An opinionated overview of the content of the manuals was created. I tried to avoid to much work and instead of changing the manuals I created a table of content which I believe newcomers will be more interested in. I'm not saying this is how table of content should look like, but it is a start we can build upon. Most importantly is that we keep in mind that target audience for this page are newcomers and visitors not that familiar with nix ecosystem.
|
I really like that I can find all the entry points easier than before. \o/ For some reason, when I want to get to the NixOS manual, I click on the "Download" button, then on the "Next Step: Manual". Not ideal :) What do you think about making the listings shallow and limit to 1 level only? IMHO, it would reduce the noise and avoid the paradox of choice. Also, not sure if it was discussed or not, I would expect the order of sections to be NixOS, Nix, NixPkgs. Thank you for the effort! |
Yes, that's also the easiest way i know. 😬 |
Download page(s) will be done in some other PR. This PR is only about
For now I think this is enough. I hope we can actually improve the table of content of all the manuals and organize them a bit better. I think topics that I exposed here might receive their own tutorial at some point and then this wont be an issue anymore.
We will have a discussion about this next meeting. What to put first, what second, what to emphasize,etc... |
|
In spirit that this already improved the current state I'm merging this. If you think we can even further improve this page, please send your PR. |
Two things were done in this patch:
There is only one Learn page which all learning material on there. It
used to be the case that each project had (or didn't have) a Learn item
in the navigation bar. In some cases the item in the navigation bar was
called Manual which broke the consistency of the website and most
importantly the expectations of the visitor.
An opinionated overview of the content of the manuals was created. I
tried to avoid to much work and instead of changing the manuals I
created a table of content which I believe newcomers will be more
interested in. I'm not saying this is how table of content should
look like, but it is a start we can build upon. Most importantly is
that we keep in mind that target audience for this page are newcomers
and visitors not that familiar with nix ecosystem.