2022-11-10 Documentation team meeting notes #15

Development Documentation
1

From team lead @lucperkins: Apologies for getting behind on this!

Attendees: @lucperkins @mic92 @infinisil @brainrake @fricklerhandwerk @edolstra @domenkozar
GitHub project: Nix documentation · GitHub

  • Agenda item: nixos.org

    • @lucperkins is working to convert the site to Hugo and Markdown. Green light from marketing team.
      • Expected outcomes
        • Dramatically easier to contribute to
          • Works on all “default” systems
          • Tailwind for CSS
          • Alpine.js for JavaScript (replacing jQuery)
          • Structured data when possible (TOML/YAML/JSON), e.g. for /community
        • Potential reshuffling of content landscape
      • Steps
        • Convert common styles to Tailwind (from Less)
        • Get nixos.org building with the new common styles + new static site gen
        • Integrate the new build with the Nixpkgs manual, etc.
      • Time frame: hopefully done by December
    • Marketing team minutes from relevant meetings: NixOS Marketing Team: Meeting agenda - Google Docs

  • Agent item: nix.dev

    • Current concerns
      • Copyright remains with Domen
      • Some content is quite opinionated (best practices, etc.)
      • Some “marketing”-adjacent content around e.g. Cachix

  • Domen himself enters the conversation

    • Wants to donate the domain to the community
    • Domain transfer needs to happen
    • What does the community want?

  • @fricklerhandwerk offers some thoughts

    • Undecided on structure
    • John Ringer and others are currently writing a Nix book
    • Separation of concerns? Only tutorials, only guides, pick one?
    • Potentially everything that isn’t in the manuals and reference places

  • @infinisil

    • A default place to go for Nix and NixOS
    • Already on a good path, but need to continue

  • @domenkozar

    • Many possible ways to “set up the chess table”
    • Barriers should be based on audience, not based on technical considerations
    • Question from @infinisil: all four diataxis quadrants in one place? Is that the goal?
      • @domenkozar: yes. One search for all docs and everything, etc.
      • @infinisil: one potential snag is that reference docs should be tied to source
      • @fricklerhandwerk etc: that’s fine, that’s what we already do in terms of rendering
    • There seems to be a rough consensus around content parameters for nix.dev
    • @lucperkins: I’ll come to the meeting next week with a rough action plan that includes achieving consensus on what should be modified or removed to make nix.dev a proper community resource
    • @fricklerhandwerk: we can do community polls etc to determine what people take to be best practices
      • Let’s prioritize what’s most important: ironing out major use cases, especially contribution
      • @infinisil: polls should be more “objective” and less about controversial things like preferences
      • @fricklerhandwerk: let’s start with low-hanging fruit like making it official