Nixpkgs manual: Don't render Contributing section

[infinisil]

Problem

The Contributing section should not be rendered in the Nixpkgs manual, because it's not something users of Nixpkgs need to know. Only Nixpkgs developers need to know that, and developers can read Markdown files in the source code directly or see them rendered on GitHub.

Compared to user-facing documentation, contributing documentation is closely tied to the source code. This gets especially annoying once we try to expand the contributing documentation to explain how to contribute to more specific parts of Nixpkgs, because we don't want to create a separate section for each part of the source code.

This is motivated by the new draft file structure documentation which talks about various directories and files in Nixpkgs. We should create README's in these directories that explain them in more detail (which I did for lib in #244044), but it's awkward then because why is only the general overview rendered and not the individual parts.

Also, the rendered manual progresses with releases and channel updates, which makes sense for users, but contributors shouldn't orient themselves on those, because they might be outdated. Instead contributors should always look at the latest state of the main branch.

Proposal

• Move the contents of the Contributing section into fitting Markdown files linked to from the root README.md file in Nixpkgs
• Replace the Contributing section with a link to where the table of contents has been moved.

[RaitoBezarius]

Users do read the whole staging thingie to understand what's going on and why their changes or awaited changes are still not here.

Same goes for backport policy in general IME.

[infinisil]

@RaitoBezarius Those are contributors though, not users. The distinction is that users only use the (unspecified) Nixpkgs API and don't need to know about Nixpkgs internals. Whereas contributors actually make changes to Nixpkgs internal structure that can affect the API (such as adding a new package).

[RaitoBezarius]

@RaitoBezarius Those are contributors though, not users. The distinction is that users only use the (unspecified) Nixpkgs API and don't need to know about Nixpkgs internals. Whereas contributors actually make changes to Nixpkgs internal structure that can affect the API (such as adding a new package).

Hm, I don't know if what I said was confusing but, users do read the whole thing about how staging gets merged, etc. They do not contribute, but they are interested into understanding the process because they want to know when X or Y lands even if they are not developer/contributor or whatever.

I agree with your paragraph except the first sentence.

[infinisil]

Ah thanks for reiterating, I accidentally only read "their changes" and not the "or awaited changes".

Good point, I think these parts should be kept in the manual then, though we could reword/restructure them to make it more useful to users.

[infinisil]

Another unrelated reason for doing this: By talking about the file structure from the rendered manual, we make the weak implication that the file structure is part of the API and stable, when it really shouldn't be.

[fricklerhandwerk]

@infinisil The distinction between users and contributors is faint and it should stay that way. We want contributions to be easy enough for any sufficiently motivated user to become a contributor.

I don't think it's wrong to have contribution guides in the manual. There is an unwritten convention to use the latest build of the manual for that purpose, and we could just make it explicit. I agree with the rest of your problem statement though:

• Interspersing user and contributor documentation is highly confusing.

  This should be fixed by changing the structure of the rendered manual accordingly

• Maintaining documentation sources that are all over the place is cumbersome and error prone.

  Having READMEs in each directory is probably a good idea, and we should also render them to the manual. We should not expect all users or contributors to navigate GitHub or even find the plain source files. The web, despite all its flaws, is still the most accessible digital technology we have in practice. We'd be missing out on a lot of mindshare if we hide away the crucial onboarding bits from our largest audience.

[infinisil]

We want contributions to be easy enough for any sufficiently motivated user to become a contributor.

Agreed, but I don't think we need the contributing section to be rendered in the manual for that. I think it would be better to just link to the source code README.md from the start of the Nixpkgs manual. This allows users to still discover it, but also have the source of truth be the main branch.

We should not expect all users or contributors to navigate GitHub or even find the plain source files.

Users no, but contributors definitely need to know how to navigate GitHub and git, otherwise they can't contribute.

If we want to allow users without GitHub or git knowledge to contribute, we should have a brief section showing how to navigate GitHub and git, or better yet, link to tutorials explaining that.

[proofconstruction]

I am in favor of the initial proposal in the OP.

---

Some notes:

The distinction between users and contributors is faint and it should stay that way. We want contributions to be easy enough for any sufficiently motivated user to become a contributor.

Yes. I included a section on preparing a new package for contribution to nixpkgs in NixOS/nix.dev#650 for this reason. Generally I believe we should always try to open that pathway with our documentation.

There is an unwritten convention to use the latest build of the manual for that purpose, and we could just make it explicit.

We should document and version-control these conventions whenever possible.

Interspersing user and contributor documentation is highly confusing.

Agreed. General users aren't reading the manual with the intent to contribute to Nixpkgs, they're trying to solve a problem they've encountered or understand something they've read. Similarly, contributors aren't checking the manual for general usage guides, they're looking for longer-form API documentation than what they could get from comments in the codebase. To use the Diataxis model, the manual should not be both how-to guide and reference. Much of the recent energy around documentation is fundamentally about resolving this tension, in part by moving things out of the manual and into nix.dev.

We should not expect all users or contributors to navigate GitHub or even find the plain source files.

This is true for non-contributing users. With contributors though, for better or worse (and I have a lot of opinions here) GitHub is a large part of where work gets done, and contributors need to have enough facility with it to navigate, read, and communicate, so they can gain the necessary context (from discussion like this on Issues and PRs) for their contributions to be relevant.

Strictly speaking, non-GitHub git-users can also make contributions to nixpkgs, but outside of adding/updating a package or module they will probably not understand how any part of the project is developing over time.

The web, despite all its flaws, is still the most accessible digital technology we have in practice.

Agreed. We should lean into more accessibility as a general rule, but it feels inevitable to have a web component to this work anyway, for technical reasons as much as sociopolitical.

If we want to allow users without GitHub or git knowledge to contribute, we should have a brief section showing how to navigate GitHub and git, or better yet, link to tutorials explaining that.

I'm in favor of this; after working on documentation around workflows lately, I'm thinking more and more that the project needs this. Git is a pretty fundamental part of the way Nixpkgs works in practice, and this dependency is even made concrete with Flakes.

Certainly there is a certain amount of technical maturity necessary to use tools in the Nix family, with even more required to participate in their production. All of that is teachable, however, and it's my belief that we have a duty to try and teach it, and not just on the docs team.

We'd be missing out on a lot of mindshare if we hide away the crucial onboarding bits from our largest audience.

Agreed. It should be possible for people who aren't software developers by trade to use and contribute if they'd like to, or else we alienate everyone else, from professional devops engineers to homelab sysadmins to data analysts to folks who just like Linux and want a nice desktop distro.

I don't see this year's survey results yet, but on these matters last year's report was unambiguous.

[zmitchell]

I'll say as a new contributor having contribution instructions in two places (GitHub and Nixpkgs Manual) is less than ideal and I would vote for consolidating them into a single document.

I don't think it's an issue to have the contributing section in the user-facing manual, it's pretty clearly meant for contributors and gaining new contributors. However, most software projects keep the contribution instructions near the code, which I think makes more sense than having it in the manual.

[fricklerhandwerk]

@infinisil @proofconstruction @zmitchell thanks a lot for these thoughtful arguments. That's why I love this place.

How about we make CONTRIBUTING.md the entry point for contribution guides, where we provide overview and guidance for navigating the code; link to that from README.md; and also link there from the manual and leave a note that amounts to

contributors definitely need to know how to navigate GitHub and git, otherwise they can't contribute [effectively].

and provide links to tutorials?

I would put particular emphasis on phrasing it compassionately. We have to state the fact that you have to gain some proficiency with the tools that are carrying this project – for better or worse – if you want to make a meaningful contribution (and we can't afford to teach you all of that), but also that we're not doing that for gatekeeping.

Related: #184971

[infinisil]

@sternenseemann What do you think of this?

[proofconstruction]

How about we make CONTRIBUTING.md the entry point for contribution guides, where we provide overview and guidance for navigating the code; link to that from README.md; and also link there from the manual and leave a note that amounts to

contributors definitely need to know how to navigate GitHub and git, otherwise they can't contribute [effectively].

and provide links to tutorials?

This sounds good. In the interest of opening the user -> contributor funnel as early as possible, I also think we should even consider adding a link to this in the navbar on nixos.org (perhaps to replace the Blog link to the NixOS Weekly which currently gets no love)

[infinisil]

Another reason why we should do this: The contributing section is currently available in the stable manual, so users could read a contribution section that is outdated by up to 6 months (until the next release). We could try to ensure that all changes to the contribution section get backported to stable, but that seems like a pain. Always linking users to the main branch's CONTRIBUTING.md won't have that problem.

[fricklerhandwerk]

That's not a reason for moving contribution guides out of the manual; there are multiple equivalent solutions as discussed above: we can just as well link to the latest manual build for that purpose.

[infinisil]

Well if we link to the master branch from the manual, both people reading the stable and the unstable manual will be linked to the up-to-date contribution guidelines. Whereas if they're inlined, everybody reading the stable manual could read outdated information. And the stable manual is the one that's easiest to get to from nixos.org.

[asymmetric]

@infinisil should this instead be labeled as 6. topic: documentation?

[infinisil]

We discussed this in the docs team meeting today (discourse bot should link to the notes once posted), where we agreed to do this. I will try to do this at some point

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-07-20-documentation-team-meeting-notes-65/30876/1

[infinisil]

I started implementing this here: #245243

[fricklerhandwerk]

Fixed by #245243

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-08-21-documentation-team-meeting-notes-74/32083/1

[nixos-discourse]

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

https://discourse.nixos.org/t/a-roadmap-for-the-documentation-ecosystem/42328/4