2023-07-31 Documentation team meeting notes #68

Development Documentation
1

Updates

  • @mightyiam: working on doc testing
  • @henrik-ch: looking other alternatives to the current manual rendering
    • ryantm’s mmdoc already has a nicer manual, but unstyled: Preface | nixpkgs
    • can take the CSS from the current manual and fit it to mmdoc
    • @proofconstruction: concern about alternative static site generators is support for our markdown extensions (these should be listed somewhere so we can address this directly)
  • @proofconstruction: Back from vacation
    • Updates
    • Want to discuss how we can build better/any relations with the parallel documentation team contributing to the wiki.
      • Some things, like the Installing NixOS on a Raspberry Pi tutorial should probably just move there.
      • A lot of material on the wiki is presented primarily in the form of what we call “Recipes”/what diataxis calls “How-to Guides”, which are currently very limited on nix.dev
      • It seems (to me) quite natural to have the Wiki be a place where documentation grows organically, and at some point gets harvested to become official documentation on nix.dev or elsewhere.
        • This workflow requires a much higher level of coordination between (the ownership of and contributors to) the unofficial wiki and the official docs teams.
    • Want to revisit our stance on flakes
      • Currently, the documentation around the flakes feature is distributed in too many locations:
      • While there are upsides (letting a hundred flowers bloom), this has several downsides:
        • Over time, more docs in more places are not making it less complicated to onboard
        • People ask for help with flakes in all the various official and unofficial channels almost on a daily basis, e.g. this recent issue,
        • In the official channels, we have essentially nothing to offer (beyond the brief nix.dev page) despite the feature being available today behind a flag in the nix provided by the official installer, and even enabled by default by the DetSys installer
      • We’ve discussed what to do about flakes documentation on several previous occasions, and collectively seem to be sticking to a few points
      • Given the level of demand for this documentation, the social importance of this feature, and the fact that it’s a de facto standard already, I believe it’s worth reconsidering our path.
        • While I agree that we shouldn’t generally be responsible for documenting unstable features (particularly because this can result in both linkrot/docs-drift as changes are made and also because it increases the burden on the under-resourced team), I believe we should have something to say, more than we currently do on nix.dev and in the manual, even if it’s just the existing nix.dev page plus e.g. “as of the time of writing, this feature allows for {list of functionalities enabled by flakes}”
        • flakes are available only behind the experimental-features flag, but the flake.nix schema is already documented in the stable nix manual, and even the official repositories for nix, nixpkgs, and the NixOS.org homepage are using flakes!
      • My opinion on this is fluid, but lately I’m wondering if not addressing this particular feature and its early uptake by so much of the community is shooting ourselves in the foot as a project ecosystem and community.
        • The project’s (Nix/NixOS/Nixpkgs) importance to the broader user-base is outsized relative to the quite-small number of people contributing to it, and many of those users are using flakes.
        • Not properly acknowledging a component that is used so widely just adds more potential to further fragment the community by spawning so many load-bearing unofficial docs.
        • The feature is even already official in practice, and I believe it’s our duty on the Documentation Team to document what is, rather than what ought to be.
2 Likes
2

@proofconstruction does FAQ: should I enable flakes by fricklerhandwerk · Pull Request #547 · NixOS/nix.dev · GitHub address some of the points you brought up during the call? The issue of whether nix.dev should document flakes is one that came up a few times before (once possibly while you were taking some time off), so if there are more things you’d like to discuss, I suggest waiting until more people are back from their summer breaks, so that there’s more context in the room.

1 Like