Format: Define order of sections in reference
Nobody has claimed this yet.
- Dominant language
- Nix
- Stars
- 4k
- Forks
- 339
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 7
Description
Proposal
Right now different manuals and different sections of these manuals across the Nix ecosystem are all over the place in terms of if, where, and in what form the following information on functions or commands is presented:
- description
- interface
- arguments
- examples
- additional context
where arguments can (should) have a small-scale variant of the same structure.
There is no authoritative rule reviewers can point contributors to in cases where documentation is structured by hand, and also no rule to follow for designing automated tooling for consistent presentation.
Proposal
It is should be the documentation team's responsibility to define such rules and present them in a visible location in order to ease successfully contributing to the ecosystem.
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 by reviewing the existing manuals and sections that describe functions or commands, focusing on how descriptions, interfaces, arguments, examples, and additional context are ordered. Done means an authoritative section-ordering rule is defined and published in a visible documentation location for reviewers, contributors, and tooling designers.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100