Tasks/notes for self:
-
sync contribution guides namely:
nixos.org
- How to Contribute- Nix manual - 9. Contributing
- flesh out the 9.1 Hacking section because it doesn't even mention that Nix is written in C++... A good start would be to also adding adding a
CONTRIBUTING.md
(see this, especially the last 4 sections - warning: it's not thenixos/nix
repo! -, and scour their readme too)
- flesh out the 9.1 Hacking section because it doesn't even mention that Nix is written in C++... A good start would be to also adding adding a
- Nixpkgs manual - Chapter 24. Contributing to this documentation
- NixOS manual - Chapter 72. Contributing to this manual
- nixos.wiki - Nix Community > Contribute
-
how to contribute to the nixos.wiki? That is, could figure out page edits, but how does one add a page? Or propose an addition? Writing guidelines? Where to put stuff? Found NixOS Wiki:Contributing, but it could probably be improved as some pages (e.g., Documentation Group, Documentation Gaps) are not added to any category
-
There is this bit:
Development of the wiki and other community initiatives happens at at the
nix-community
Github repository. The #nixos-wiki channel on Matrix is available for questions.There is also a Maillinglist where you can submit patches if you prefer to submit patches via email. These will then be forwarded to Nixpkgs as a pull request by someone on the ML.
-
- nix.dev - How to Contribute
- what else?
-
"format-aware"/technical contributions
- is there a GitHub issue template for docs? (either way, if the suggestion is in more general in nature - i.e., not related to specific content, proposition for an over-arching structural changes to the manual triumvirate, etc. -, advise person to make a "format-agnostic" feedback; GH issues tend to remain hidden from the larger public eye)
- general GitHub PR and issue guidelines
- use documentation tag
- open issue in the right repo (make sure to link to the right repo when updating the contrib guides!)
- make it clear what the official documentation format is (RFC 0072)
- what is the status of docbook -> markdown migration?
-
propose avenues of "format-agnostic"/non-technical feedback
- by writing a post on Discourse in "Development > Documentation" category
- draw up draft of general guidelines
- what methods are the most effective? (not "accepted" - every feedback is important)
- support web annotation tools
- hypothes.is notes will get "unmoored" when site changes -> would be nice to get a snapshot URL for a specific report (3rd party solution: create Internet Archive snapshot, annotate, and share)
- are such content changes an issue for other tools? if they can share annotations, will they be guaranteed to stay?
- encourage new ideas
- add Discourse topic template(s) to report doc issues
- draw up draft of general guidelines
- by writing a post on Discourse in "Development > Documentation" category
-
repository for documentation tasks
- both for actionable (e.g., nixos.wiki's Documentation Gaps) and theoretical ones (i.e., propositions that may be fundamentally different from the current official course; maybe someone would feel inspired to give one a go to see if it works for others)