2024-05-06 Documentation team meeting notes #123

Development Documentation
1

Notes

  • @klinger: what to do with configuration guides in the NixOS manual?

    • most application-chapters are quite distracting and may be better placed in the wiki, it would be better to have a clear focus on the operating-system stuff.
    • The choice of applications in the manual is bizzare. Examples: Why aren’t there Firefox and Thunderbird chapters? Why is the server component taskserver described at length? Everybody uses a browser, only a few will host the server component for this very nice CLI todo app.
    • It would be better to have a more structured approach in the NixOS manual for the applications (with categories like Desktop environments, shells, games, office-software, …)

  • @fricklerhandwerk

    • On the short term it is probably ok to link manual entries in the wiki and extend the knowledge there. Its important to avoid to have to edit the information in two places
    • It’s also ok to join/delete the wiki categories with only some articles (like guides/pedias/cookbook) - but this may need some more discussions
    • Ideally we’d have the information in the code. One could take a structured approach to arrange the code and thus documentation by use case or “application” that would span over several modules and derivations, and also support tested examples that way
    • We’re currently trying something like that in the NGI project with @lorenzleutgeb:
    • I can imagine to work on prototyping this approach for NixOS in the upcoming sessions, it may need a couple of hours - then we can categorize and document in-tree and we automatically get a better manual.
4 Likes