2023-06-15 Documentation team meeting notes #55

Development Documentation
1

Agenda

  • set new priorities for funded documentation project
  • updates and blockers

Project priorities

Due to our Editorial Lead @maj not being able to work on the documentation project for health reasons, we have to adjust priorities. @maj has already been extremely helpful even in a short amount of time, and may still give advice here and there as far as possible. We considered making a new call to fill the role, but it would take additional time and we deem it very unlikely to find someone with that particular skill set on short notice.

Therefore, we decided to slightly shift focus for the overall project: We will de-emphasise the curriculum design and put more effort into reorganising documentation and improving discoverability.

This mainly means that ongoing work will continue on its current course we set in the past weeks:

  • The learning journey working group lead by @zmitchell will focus on creating tutorial outlines and continue work at their own pace determined by available volunteer time.
  • Volunteers and paid contributors will be coordinated by @fricklerhandwerk and expand the documentation survey and help with migrating and reorganising materials. We will allocate additional budget for that work.
  • Our dedicated Nix expert @roberth will continue supporting the group with reviews and technical tasks. We will also allocate additional budget for @pennae’s technical work on documentation infrastructure.

We’re confident that this will still get us quite close to the original project goals in the upcoming months.

Complete discussion
  • @fricklerhandwerk: Given we have no Editorial Lead any more, we need to communicate that we can’t implement the curriculum project as planned
    • Discussed alternatives with @maj and @roberth
    • Most budget is still available
    • We have discussing a lot because of the overall complexity
    • We ran into technical/infrastructure issues
    • Therefore proposal:
      • Use at 50-70% budget to focus on the Nix manual, reference documentation
        • Let @roberth do Nix and Nixpkgs docs infrastructure stuff, supporting @pennae
      • Leave the rest for assisting the LJWG with the documentation survey, collecting materials
        • Make larger contracts with continuous contributors for more throughput
    • @zmitchell: Collected funds to make Nix easier to approach, which this doesn’t really do.
      • @j-k: Agree, it’s important to get onboarding docs good, otherwise can lose users for a long time
      • @fricklerhandwerk: Would definitely communicate why we can’t do the original idea as planned, and how to shift focus to something that is likely to succeed
    • @infinisil: Nix reference docs isn’t that important.
      • For example, derivations are used by everybody but not necessary to understand.
      • Better reference docs for Nixpkgs or tutorials for onboarding might be better
      • @fricklerhandwerk: Focusing on Nix first is to build a foundation, since everything depends on it. Hitting problems with that when reviewing anything else, inluding Nixpkgs documentation.
        • Doing reference first is essentially what @Ericson2314 has been suggesting all along
      • @j-k: Developers would benefit from reference docs, but there’s also many devs that don’t want to touch C/C++
        • @infinisil: Nix manual is not about C/C++, it’s about CLI, language, etc.
    • @j-k: Maybe should demonstrate cases where existing reference documentation is lacking to convince people why it’s necessary to prioritise those
      • @fricklerhandwerk: Primary example is the Nix language reference, very poorly documented with respect to impact. E.g. no overview of the syntax, few examples.
        • The language is also the widest interface for Nix
        • @zmitchell: I don’t think this is the bottleneck for people learning Nix. The language seems to work well enough for people, haven’t run into a language-specific problem.
          • Bigger problem is people don’t know where to find things.
    • @zmitchell: Idea: Let’s use the funds to reorganize the documentation.
      - Primary example the Python section in the Nixpkgs manual, containing various types of documentation, but hard to find and navigate. People don’t tend to go to reference manuals for that reason.
      • @infinisil: Agree, but also infrastructure is needed to make that work nicely.
      • @fricklerhandwerk: How to phrase it? Make reference docs actual reference docs. (But without focus on NixOS, would be too much). Migrate non-reference to nix.dev
        • @infinisil: Migration or improving infrastructure to make it easier to maintain things.
        • @zmitchell: I don’t think we should focus on reference docs this much
      • @j-k: Improving infrastructure would help with learning journey, reference is also important sometimes
    • @fricklerhandwerk: Focus on discoverability, drop curriculum
    • @fricklerhandwerk: So the answer: Do more shoveling, less curriculum, learning journey WG continues at their own pace, who to use funds for?
    • @infinisil: @roberth and @pennae for infrastructure work for now
    • @fricklerhandwerk: Scale up work and pay for contributors. @maj could still consult with us on much smaller scale when needed.
    • @proofconstruction: Time constraints?
  • @fricklerhandwerk will write up a statement in the notes, team will review

Updates and blockers

1 Like