nix.dev

nix.dev copied to clipboard

It is difficult to find information across the different layers of documentation

(the suggestion is based on my experience with the existing documentation that is spread over multiple places and not a comment on the current book project.)

I see the value to keep separate books, but this separation of concern should be balanced with an effort to link between the different documents. Therefore I suggest:

1. Add more links between the books and the wiki.
2. Make use of paged documentation in the NixOS and nixpkgs manuals, as used in the nix manual, so that at the bottom of each section is space for links.

@olafklingt do you think the following would help navigation?

• graphical outline to the guides (https://github.com/NixOS/nix.dev/pull/265)
• graphical outline of information architecture (https://github.com/NixOS/nixos-homepage/pull/875/, specifically this diagram)

@fricklerhandwerk your PRs are helpful for the macro view. But the suggestions I made focus on linking between sources within the documentation, so that you know where to look for more details while reading on a specific topic (micro view). Unfortunately this issue is formulated so general that its not really "solvable" linking can always be improved. Should I move this into a discourse topic?

I had also added a long-standing task for adding links in the Wiki in the documentation team contribution guide. While this is not publicly visible yet, the same information is in the address to Summer of Nix 2022 participants.

One more specific thing you could do is by checking Wiki contribution guides if they have similar suggestions, and add them where you see fit.

Should I move this into a discourse topic?

I don't think this deserves more discussion, let's just instruct potential contributors to do that and meanwhile try to set examples ourselves.