scope of contents and team efforts

[fricklerhandwerk]

• it is not clear yet what the documentation team should maintain as a central learning resource and what should merely be referenced
• proposal:
  • include:
    • guides to using Nix package manager with nixpkgs
    • best practices
    • high-level explanations and interplay of ecosystem components
  • reference:
    • Nix, nixpkgs, NixOS manuals
    • nixpkgs language-specifics
    • tools from the ecosystem (especially NixOS, home-manager) and guides to use them

[mcdonc]

Hi folks!

I'm not entirely sure how I can best help, but I would be interested to if I could.

Prior experience: primary author of the "The Pyramid Web Application Framework" at https://trypyramid.com/documentation.html

Interest in Nix: https://www.youtube.com/playlist?list=PLa01scHy0YEmg8trm421aYq4OtPD8u1SN

[fricklerhandwerk]

Hi @mcdonc, thanks a lot for reaching out!

The organizationally easiest way to help would be picking any of the long-standing tasks outlined in the contribution workflow draft. They should be fairly granular and require the least commitment.

Given your experience I'd very much like to see you contributing to more involved issues. We don't have them laid out yet, though. What would you be interested in doing? Maybe you can formulate it as issues. Maybe you can share what you have learned from the Pyramid effort, for example by adding best practices to contribution guides.

[mcdonc]

Hi @fricklerhandwerk , thanks for the response!

I suppose if there was a proposed outline of the book's table of contents, I would dive in and try to take a chapter. For instance, maybe something like "Installing NixOS" or "Understanding Channels" or "Using nix-shell", etc, etc. At the moment I could promise to write one chapter like that, and thereafter possibly more. I am also available to review and edit other submissions as necessary.

Writing the Pyramid docs gave me a good deal of experience producing multiple media outputs (e.g. HTML, PDF, ePub, and dead-tree printed medium) from a single set of input documents. But that experience is mostly limited to bending Sphinx and reStructuredText to do what we needed.

I'll take a look at the links you sent. If there's a better place to talk about this please let me know.

Thanks!

• C

[fricklerhandwerk]

@mcdonc for an idea what should go into the book we have

• visual outline
• textual outline

Best place for discussions is on Discourse. Or open an issue here for something specific you want to make happen or get decided.

On your proposals, all of which would be great additions:

• "Installing NixOS" should be covered in the NixOS manual (source)
  • direct all improvements there, we will help getting them merged
• "Understanding Channels"
  • personal opinion: we should make clear channels should be avoided, explain why they are problematic, and remove all recommendations to using them from any material we have access to
  • should still be properly documented under imperative package management
• "Using nix-shell"
  • that already exists as Ad hoc developer environments on nix.dev (source)
  • still have to decide whether or how to include that in the book: NixOS/nix.dev#284

Let us continue this on a thread, issue, or pull request for the respective items you're interested in working.

[mcdonc]

Thanks @fricklerhandwerk ... I wasn't pointing those out as specific things I would like to tackle, just as an example of the kind of specificity it likely requires ("please go write X") to get involved. But I'll take it to Discourse.

[fricklerhandwerk]

@NixOS/documentation-team

The past months saw a convergence on a few key issues in Nix documentation:

• learning the Nix language as a centerpiece to the learning journey (#267)
• providing overview of the ecosystem (https://github.com/NixOS/nix/pull/6888, https://github.com/NixOS/nix.dev/pull/265)
• helping contributors (How to contribute to documentation)

As noted in my report I think we should next focus on onboarding and enabling contributors.

The rationale behind this is that there are just too many construction sites for any small group of people to keep track of. As I have experienced first-hand in the past months, getting input from users is not enough - the capacity required to act on it is an order of magnitude more than what we have available.

Essentially I'm thinking about a kind of meta-documentation that describes the process of developing the Nix ecosystem (including documentation) and provides potential contributors with everything they need (including realistic expectations) to successfully get (significant) changes merged into Nix, Nixpkgs, or NixOS. Ideally we could get a step closer towards balancing influx of pull requests with available maintainer time. That may entail making more explicit what the overall process looks (or should look) like, clarifying priorities, and also removing roadblocks towards higher-quality pull requests.

While gaining overview and enabling contributors goes hand in hand, there are still different requirements for beginner users, people who want to contribute to documentation while learning, and people who are already (semi-)proficient and want to work on the code. This is a bootstrapping problem. We actually want to pave ways for all of them at once, but there is only very limited time.

I would like to figure out together the least-effort highest-value objectives we could focus on for the next period. Specifically:

• What are the most pressing pain points when trying to introduce changes to Nix, Nixpkgs, NixOS?
• What are the highest barriers to improving documentation?

Maybe we can sketch user stories for contributors, contact Summer of Nix participants for testimonials, possibly conduct another round of user studies?

[fricklerhandwerk]

• @fricklerhandwerk would like to collect experience on the pain points in the contributing process
• @Mic92 simple fixes go in quite quickly, but larger PRs often get lost and stall
  • had a NixOS meeting to go over systemd PRs - would that make sense for the documentation team?
  • having links between documentation and its source would be helpful to find the right things
    • would reduce the amount of errors, but not necessarily help with quality
• @mightyiam should start with documenting that onboarding is an issue, and which problems there are in detail
  • don't need a resolution to open an issue, can be as general as need be
  • found a lot of issues in documentation while sorting through the user studies
  • possible list we can work off to create issues:
    • Nixpkgs contribution guidelines are massive
      • description of directory structure is confusing (because it's procedural rather than declarative)
    • finding relevant documentation is hard
  • in order to get started with things one has to learn all of the components, this is in the nature of Nix, bringing all these technologies together
    • for a single person it's nearly impossible to make a significant contribution and must be very frustrating
• @fricklerhandwerk all in favor for more issues to keep track of things, but they should be specific enough - "onboarding is hard" is very general and there is no criterion to close it at some point. getting a big picture and breaking out more concrete issues is the objective today. what do the others have to say?
• @Ericson2314 the company I work at hires people who know some Nix self-taught, and we have a handbook for our specific stuff
  • we don't contribute large changes to Nixpkgs/OS, but we sometimes have to build complicated things for clients
    • we have people who are very strong in Nix and they just do that
  • things my coworkers complain most about:
    • Nix has a lot of rough edges
    • Nix language has no types
    • all the software Nix is dealing with is in a bad state to begin with
      • Nix reveals all of it and prevents us being blissfully ignorant about it
• @mightyiam the path to contributing should be pretty clear: there is documentation for it. but you have to find it. - @Ericson2314 need a tool to render reference documentation from the code (the equivalent of Haddock, Doxygen) - @infinisil more generally making the docs live closer to the code - @mightyiam that is the single most important thing that would make documentation work at scale - it seems Nix doesn't have this - @fricklerhandwerk do we have tooling to parse Nix language and output an AST? - @infinisil https://github.com/nix-community/rnix-parser - @Ericson2314 should start writing documentation in source already, already a win, we can later fix the format - @fricklerhandwerk we do this in Nixpkgs and it is double book-keeping - type annotations to render in the documentation
  • if we went over the contributing story we'd see many obvious issues on the way
• @infinisil the next big thing should be documenting Nixpkgs better, because that is what attracts people to the ecosystem
  • improving structure and completeness, such as making the documentation live closer to the code
  • @Ericson2314 agree, having doc and pkgs separately is one of the problems contributing to diverging code and docs
    • have to focus on the experts first by improving reference documentation, and eventually we'll end up with beginners
      • @infinisil reference documentation will manifest the API
    • @fricklerhandwerk agree with everything, but reference documentation is not the only thing we care about
      • problem: improving reference needs expertise, but building expertise is very expensive. we have to pick up intermediate users to become contributors to help with these issues.
        • it's a magic triangle: reference documentation — user onboarding — contributor onboarding
      • @Ericson2314 we should delay tutorials/guides before we make sure reference documentation is solid
• @fricklerhandwerk how would we address such a large scale task such as a documentation generator or improving reference documentation all the while people contribute to whatever is in place already?
  • @mightyiam prioritize from the bottom up, tackle the dependencies first
    • not afraid of putting the world on hold
      • the project works with the resources that it has
      • if there is something important enough for an entity, that entity will pay for seeign progress
      • the healthiest organic development will be from the core out
  • @mightyiam what are our resources concretely?
    • me and two people want to spend at least 6 hours a week to improve things, can we go somewhere to get that funded?
      • @fricklerhandwerk this would be just great! NLnet would be an option
    • @Ericson2314 the most effective use of funding would be tooling
      • @infinisil agree, once we have tooling in place, we can enforce that reference documentation is kept up to date while maintaining code, while tutorials will always need care independently
    • @fricklerhandwerk to answer your question: we don't know exactly (yet) - IMO this should be part of the requirements to team membership: telling exactly how much time someone will spend. I will update my availability ~next week.
• @Ericson2314 tutorials are creative, single-threaded work
  • @fricklerhandwerk cannot automate this with tools
    • @Ericson2314: need domain experts to contribute reference documentation, so others can create tutorials from that, without reading the source
    • yes, it would be great if we could split these tasks up for everyone to focus on a self-contained objective, and still coordinate as a team to work towards higher-level goals
      • still, would to make clear these objectives and define priorities, so we can allocate the resources available once we know them more concretely. will propose something until next meeting.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-10-06-documentation-team-meeting-notes-10/22286/1

[fricklerhandwerk]

@Mic92 wrote

This week the first NixOS release team meeting for the next release took place. We also discussed how to handle the release notes and how to improve them. So far release notes tend to get quite large with lot of content for all the different modules added but not easy to read like a blog post. Is this release notes the Nix documentation team wants to review?

This does fall into our general responsibilities, but right now I certainly don't have time for it. I decided to mostly ignore NixOS for the time being, to better keep focus. What we as a team could (and should) help out with in the long run is provide a collection of external guidelines and good examples in other projects to take take into account for e.g. release editors. That will have much longer leverage, as this can apply to all projects in the ecosystem.

Other than that, I think it would be just fine to ping the team on specific issues or questions, or put it on the agenda for one of the meetings to discuss synchronously.

[fricklerhandwerk]

Closing since we now have documented goals for the documentation team.