Notes/tasks about making it easier to contribute to the Nix eco-system

notes_improve-nix-contribution-guidelines.md

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 the nixos/nix repo! -, and scour their readme too)
  • 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

• 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)