2023-06-29 Documentation team meeting notes #59

Development Documentation
1

Agenda

  • updates
  • module system walkthrough by @roberth

Updates

  • introducing @alejandro and @mightyiam
    • @alejandro will work on cleaning up reference documentation for stdenv
    • @mightyiam will take on reference documentation for the module system
    • @henrik-ch and @jillthornhill could focus on surveying materials for these topics
    • we will work ourselves up to support the LJWG
  • @roberth only got around to issue reviews recently, was mostly working on Nix documentation so far
  • @pennae: nixdoc PRs waiting on @asymmetric, dedocbookification waiting on nixdoc, conversion of module documentation to markdown is largely finished
    • documentation authors don’t have to deal with docBook anymore, for a while now
    • dedocbookification will remove docBook from the rendering workflow entirely
    • the current nixdoc PR will fix up markdown output to match existing semantics
    • stable URLs for released manuals need a few different steps, can help with guidance
  • @proofconstruction reviewed and updated some PRs on nix.dev and got one merged
    • started investigating for tutorials to package existing software
    • writing a guide on building shell environments for some common languages
  • @alejandrosame started annotating the Python section of the Nixpkgs manual
    • will break down issues and start with small PRs
    • @proofconstruction: a lot of material in the nixpkgs manual language-specific sections can be moved to nix.dev tutorials/guides; the Python section in particular has much to be used

Module system walkthrough

@roberth walked us through the introduction section added in doc/module-system: Introduce concepts by roberth · Pull Request #240531 · NixOS/nixpkgs · GitHub

  • discussion around: various syntaxes, where to put the note that the module system is an eDSL in nixpkgs, determining what to include in the manual vs. what to move out
  • @proofconstruction: full examples not necessary in every part of the module section, but a few lines of syntax tying definition & description of things to the in-practice implementations would go a long way, e.g. in the Option Type section.