2023-01-19 Documentation team meeting notes #24

fricklerhandwerk · February 17, 2023, 8:47am

Attendees: @lucperkins @infinisil @henrik-ch @wrover (later: @fricklerhandwerk)

Ilia introduces himself and mentions his ambition to write a Nix book.
- motivation: many devs try to read lots of things, but end up in the chat helpless
  - also they spend waiting hours on compiling the world due to misconceptions
  - verbal introduction is much more effective, but that doesn’t scale
  - suspcicion: many companies are forced to come up with their own solution to different problems
    - @fricklerhandwerk: there is evidence supporting this
- General overview with a practical emphasis
- has funding from his company
- wants to make it public soonish, ~ 1 month
- Open to collaboration
- what is the focus?
  - core Nix concepts
  - Haskell, haskell.nix, third-party projects in the ecosystem
  - More for Haskell people
  - should cover all aspects
Who else is working on a Nix book?
- @jonringer @nrdxp
  - GitHub - divnix/nix-book: The Nix Package Manager
  - some partial chapters
- @fricklerhandwerk
  - GitHub - NixOS/nix-book: Nix documentation – centralized community online learning resource for Nix
  - only a stub, has a fairly complete outline
- @fricklerhandwerk: we can reasonably estimate the whole thing to take 1.5-2 years by two people working consistently
  - evidence: the Rust book, various Haskell books
  - ideally one deeply involved in Nix and tech, one beginner
consensus:
- get together to work on one effort
  - we already have an official repository with preliminary work done, and the general idea is approved by @edolstra
- collect requirements
- draft an outline
- gather existing material
- do gap analysis
- see how to continue from there
New flake template: Provide initial flake plus README by lucperkins · Pull Request #1 · nix-dot-dev/nix-flake-example · GitHub. Ready to merge?
Other templates for nix.dev?
- Non-flake template?
- Get prominent people from the community to contribute templates
- @infinisil: Write in nix.dev template section that everbody is encourgaed to submit templates (instruction, etc.)
  - Inform people of this possibility
Team meeting time
- Current time doesn’t work for Domen
- Mic92: You're invited to talk on Matrix
Next topics for the docs team
- Markdown transition
  - @infinisil: this is worthwhile because when we succeed it would make contributions a lot easier
  - @lucperkins: In principle it’d be good to have a unified toolchain
    - have to collect requirements
  - invite all people involved in the multiple ongoing efforts
    - @ryantm (Nixpkgs to markdown + mmdoc)
      - Happy Docsgiving 🦃 - #28 by ryantm
      - doc: add nixpkgs manual split into multiple pages by ryantm · Pull Request #108063 · NixOS/nixpkgs · GitHub
    - @FridH (Nixpkgs to Myst + Sphinx)
      - nixpkgs manual in CommonMark using sphinx+myst and jupyter-book by FRidh · Pull Request #105036 · NixOS/nixpkgs · GitHub
    - @pennae (NixOS option documentation to markdown)
    - @tazjin (author of nixdoc)
      - GitHub - nix-community/nixdoc: Tool to generate documentation for Nix library functions [maintainer=@infinisil]
    - @garbas @ncfavier (authors of search.nixos.org)
      - GitHub - NixOS/nixos-search: Search NixOS packages and options
    - @edolstra (migrated Nix manual to mdBook)
  - @lucperkins will write an invitation
    - when2meet.com from 2 weeks to 4 weeks ahead
- observation: there is an infrastructure and an editorial side to documentation, mostly orthogonal problems
  - @fricklerhandwerk: have to work on both, do we have the resources to do it in parallel?
    - editorial problem: need tutorials and guides, but it’s really tedious to write them when reference documentation is inadequate
    - @Ericson2314 suggested to fix the reference first, then the rest will come much more easily
    - we need all four Diataxis types
      - simplified: bottom-up (principles, interfaces) and top-down (use cases, skills)
    - (general agreement)

Solene · February 17, 2023, 8:49am

Cool to learn a Nix book should be out soon! Thanks for your updates

fricklerhandwerk · February 17, 2023, 8:51am

Ilya didn’t literally say “out” in the sense of “finished”, but the current state made available to the public for collaborative development. We quite clearly agreed that in any case we should join forces and have an official one that we all work on.

pennae · February 17, 2023, 11:52am

just want to quickly note that our (in-tree) commonmarkization efforts have progressed a lot further than just options by now. we’re on the brink of removing the last bit of docbook from the nixos manual (nixos/manual: specify manual structure in markdown by pennae · Pull Request #215973 · NixOS/nixpkgs · GitHub) and only a couple days away from being able to present a renderer that makes use of the previous PR to create a 1:1 copy of the docbook-generated html manual (according to html-tidy).

fricklerhandwerk · February 17, 2023, 3:59pm

@pennae would you like to join the team meetings to share what you’ve done and discuss how we could support you or just coordinate the efforts as good as possible? Is there a way to get in touch with you out of band?

pennae · February 17, 2023, 5:30pm

we can definitely try to join, but due to Things that probably won’t be very regular occurence. we’re on matrix in #dev if you’re there (haven’t found a dedicated dev channel we could join), but apart from that it’ll be only DMs on discourse (or possibly email).

fricklerhandwerk · February 18, 2023, 8:03am

Thanks! Discourse shows your public is hidden, therefore it always I can’t send you a DM.

pennae · February 18, 2023, 12:08pm

we had DMs enabled, so doing it on the long route (messages → new → add people) should’ve worked? no idea. made profile public again to avoid more failure points, anyway. hope this fixes the situation.