2023-06-08 Documentation team meeting notes #53

Agenda

  • progress report
  • distribute tasks to project contributors
  • managing reviews
  • if time left: reviews

Progress

Tasks for paid contributors

  • @zmitchell: Categorizing Nixpkgs manual material

    • @henrik-ch: Same thing as documentation survey work, which I’m doing, but taking a long time. Help welcome
  • @zmitchell: Not just categorizing, but also move it to the right place, make PR’s for that

    • @roberth: Problem of interlinking, want to go both directions.
      • Suggestion: Tutorials and guides should be in the Nixpkgs source while working on them at least.
      • E.g. load Nixpkgs sources into the nix.dev build to publish them. Invest into tooling to make this work smooth.
    • @fricklerhandwerk: Partially moving things around in Nixpkgs is good, fairly low context required.
      • Implementing this idea requires much more context, @roberth should do this
      • Tutorials shouldn’t be part of this. Guides should be. But maybe it doesn’t matter.
        • @roberth: There’s not a lot of tutorials in Nixpkgs anyways
  • @fricklerhandwerk: Let contributors help providing overview, categorization, maybe picking apart the Wiki as well, let @roberth do infrastructure

  • @zmitchell: Nixpkgs content categories are mixed, can’t easily be separated.

    • @roberth: Everything inside Nixpkgs would be better, more integration
      • @henrik-ch: Merge nix.dev into the Nixpkgs repo?
      • @fricklerhandwerk: Doesn’t matter where the information lives, have to compile it into an overview in the end.
        • Not opposed to the monorepo idea.
    • @fricklerhandwerk: Currently there’s too much arbitrary interleaving, people shouldn’t have to read the reference material back-to-back.
  • @infinisil: nix.dev just as the infrastructure repo pulling content from various official projects, Nix, Nixpkgs, NixOS. NixOps, Hydra, too?

  • @henrik-ch: You can send documentation survey interests my way

  • @fricklerhandwerk: Triaging PRs and doing reviews as far as possilbe could be another thing for volunteers.

    • @proofconstruction: From my outside perspective, there’s some ideas, e.g. want tutorials and guides to move to nix.dev
      • Is there any document describing this intention? How do I know what’s tutorial, what’s guide, etc.?
      • What volunteers can do depends on their background. Some might not even be developers, maybe not familiar with Git/GitHub
        • Brute forcing requires a huge amount of effort
  • @fricklerhandwerk will assign tasks via GitHub issues to better keep track of them

doc/hacking: note a cause of ./configure failing under zsh by lf- · Pull Request #8455 · NixOS/nix · GitHub

  • No conclusion reached last time
  • That’s how NixOS Wiki and nix.dev was born, writing down various small hacks all over the place
    • We need these somewhere
  • @infinisil: Create more links from guides to issues you might run into on a different page
  • @zmitchell: Working on sphinx tags and redirects. Tagging more fine-grained requires splitting up into smaller pages, doesn’t sound good, but is an option
    • Might want something other than sphinx at some point
    • Alternatives: Roam research?, logseq?
  • @fricklerhandwerk: Not bad to have a hacky, low-tech solution as long as it works
  • @infinisil: Infrastructure seems important, keep getting stuck on it
    • @fricklerhandwerk: As long as that’s the case we can just do content shoveling to move forward at all
      • Put things on one pile instead of having multiple, would solve part of the scatteredness problem
      • Then go continuosly about sorting the piles, Diataxis is one such coarse structure