Task: Document how to take ownership over a manual section

[infinisil]

If you're interested in working on this task, reply in this issue to make sure the work isn't duplicated!

What

A section to describe what it means to take ownership over a manual section.

Key points:

• This is specifically for the Nix manual, Nixpkgs manual and NixOS manual
• Prerequisites is to have experience with the subject matter
• Include the general maintainer responsibilities section
• Determine the types of documentation contained in the section according to Diátaxis and move it accordingly:
  • The manual itself should only consist of reference documentation
  • Tutorials, Guides and Explanation documentation should be moved to nix.dev
  • Make sure to take into account redirects that should be put into place to avoid breaking URLs
  • To change Nix manual redirects see nixos-homepage/netlify.toml, for anchors redirects see nix/redirects.js
  • TODO: (@pennae) how are anchor-level redirects handled in the Nixpkgs and NixOS manuals?
• Determine the support status of the documentation and move it to the correct place:
  • Only projects under the NixOS GitHub organisation should be in the manual
  • If the docs are for a third-party project, make a PR with the docs to that project and link to the result
• Improve quality of existing reference documentaton
  • Are API listings complete?
  • Does every interface listing provide fully working, concise examples? (no placeholders)
  • All attributes and arguments should be fully documented including typing information, defaults and semantics
  • check if an (fragment) example is needed to demonstrate how it's used

How

• Where to put the result: A new section under https://nix.dev/contributing/ (source)
• Estimated effort: 2 hours
• Related:
  • https://discourse.nixos.org/t/documentation-team-call-for-maintainers/25970
  • https://github.com/NixOS/nix.dev/blob/master/maintainers/responsibilities.md
• Person to contact for help and review: @infinisil

[pennae]

• how are anchor-level redirects handled in the Nixpkgs and NixOS manuals?

basically, not. the docbook toolchain did not have (or never used) any facility to redirect from old anchors to new locations, and the nixos manual as produced by nixos-render-docs inherited that inability. it should be fairly easy to add support for that into either with a bit of javascript, although we'd probably want to integrate that into nixos-render-docs at least somewhat to ensure that redirected anchors aren't reused.

[fricklerhandwerk]

Would it make sense to adopt the script from the Nix manual? Quite some thought went into that by previous maintainers, and I invested more effort to make it as readable as possible.

[pennae]

sure, why not. and even if it proves to not be perfect for our use cases in the nixos/nixpkgs manuals, it's almost certainly a better place to start from than a void :)

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-04-04-documentation-team-meeting-notes-38/27000/1

[fricklerhandwerk]

@pennae Added a Nixpkgs issue: https://github.com/NixOS/nixpkgs/issues/224808

[proofconstruction]

To take ownership of a manual section, we should update CODEOWNERS or maintainers.nix or other, once the appropriate infrastructure is in place: https://github.com/NixOS/nix.dev/issues/543