Task: Document how to take ownership over a manual section
Open
Nobody has claimed this yet.
good first issue
- Dominant language
- Nix
- Stars
- 4k
- Forks
- 339
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 7
Description
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:
- Person to contact for help and review: @infinisil
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the contributing source directory in nix.dev and the maintainer responsibilities section linked in the issue. Review the Nix manual redirect files, nixos-homepage/netlify.toml and nix/redirects.js, then define the new ownership section with Diátaxis guidance, support-status rules, redirect handling, and reference-documentation quality checks; completion requires review from @infinisil.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100