Ideas to make it easier to contribute (not just to the documentation)

toraritte · July 12, 2022, 7:44pm

There is a Best way to contribute to documentation? topic, but the intent of it slightly different and now that we have a Documentation Team now (announcement, meetings), it seemed like a good idea to start a new thread.

TL;DR
It would be helpful if uniform instructions would be provided for both technical (“format-aware”) and non-technical (“format-agnostic”) contributions.

Technical contributions

By technical or “format-aware” contribution I mean an edit suggestion that comes via pull request (PR); that is, the initiator knows git and GitHub workflows, is comfortable with DocBook & markdown¹, etc.

^{[1]: As far as I know, the migration hasn’t finished yet (basing this on #175586).}

At the moment, the How to Contribute page does not mention anything about the documentation, and the instructions are either relegated to the end of the manuals (Nixpkgs and NixOS manuals) or missing altogether (Nix manual)².

^{[2]: Or did I miss these somehow?..}

The existing manual sections also don’t mention git and GitHub workflows, such as cloning Nixpkgs, whether to open an issue first and then PR, etc. Not saying that the manuals should teach readers how to use these tools, but making Nix community conventions explicit would be perhaps encouraging.

Non-technical contributions and alternate avenues of reporting

In contrast, non-technical or “format-agnostic” contribution stands for any feedback where no PR is submitted and no documentation source would be touched.

I believe promoting official ways to report suggestions (at least one that excludes the usage of git/GitHub)³ would be important for a couple of reasons:

^{[3]: E.g., open a GitHub issue using xyz template or post on discourse in the x category and/or using yz tags}

save people’s time
One may just want to report a couple of typos, but they lack time and/or deem the effort of submitting a PR too much, so in the end they forgo doing anything altogether.
submitting a PR is intimidating
Even if there are detailed instructions, lacking familiarity with git, terminal, etc. may be a barrier.
no GitHub account (for whatever reason)
anxiety
For example, I have been following Nix and the community for a while now, but still not sure what the “proper” ways of doing certain things are. For example, where to discuss an ambiguity that I found across 2 manuals? Should I open an GitHub issue? Ask it here first? This is probably over-thinking, but I’m probably not the only one with these thoughts. One or two officially suggested way would help like minded folks to ease them into the community.
disagreement over documentation format
We all have our opinions regarding the “right” documentation format⁴, and a person may decide not to work with a certain one, but they may have valuable input nonetheless.

^{[4]: E.g., see Documentation format topic}
(else?)

This footnote requesting support for annotatability⁵ is only tangentially related, but it may also provide an additional way of feedback in complex cases⁶. My problem is that whenever a manual is updated, the manual URLs stay the same, and so notes anchored to specific text highlights become stale (“orphans” in hypothes.is lingo); that is, with the disappearance of the context, the notes and cross-refs become almost meaningless.

^{[5]: By providing permalinks for versions of the manuals; one for each major version perhaps?}

^{[6]: For example, the manuals have overlapping topics, and there may be differing explanations of the same concept; or the Nix manual is updated with a new functionality that deprecates another, and the rest of the manuals still use the old ways. Most online annotation tools allow public sharing of notes with cross-refs so one could just click the link to follow the crumbs.}

edit: distilling the Matrix conversation between @deliciouslytyped and @mat:

Try out something like the “report docuentation bug” button in the SLES docs, but one that doesn’t require signin + a thumbs down/thumbs up under each paragraph to quickly see what people like and what not.
- → On that note, the Erlang reference docs streamline making a pull request for each function (e.g., mnesia:clear_table/1):

edit-2: Change title and collect all the discourse threads in this topic that I could find. (TODO: distill)

edit-3: From the Spectrum OS community’s “spectrum-devel” mailing list:
[PATCH] Documentation: add “Sending your First Patch”

toraritte · July 19, 2022, 10:04am

edit: Moved the notes to a gist, because it was an eyesore, and instead I would like to use this space for a shout-out to @qyliss and the Spectrum community!

Their Participating in Spectrum and Contributing to Spectrum pages should be a blueprint or at least provide some inspiration for our How to Contribute guide(s): they exude warmth and hospitality while effectively quenching budding anxiety with as few words as possible.

edit-2: I also love the idea of their idea of adding a bibliography.

fricklerhandwerk · July 19, 2022, 11:18am

@toraritte thanks a lot for the write-up! It would be very helpful to have dedicated issues tagged with documentation for these things, tagged appropriately (ping me so I can add tags). Then we can link to a filtered query from the contribution guide. Transferring the pieces would be a good use of your available time, I think.

Most of the things you write are on point. here are a few exceptions:

I tried to address many of your points in the Summer of Nix announcement, and the instructions are based on pull requests to nix.dev and the website.

I would very much prefer to see pull requests for suggestions like directly. If you see something missing, write down the obvious thing or whatever you come up with, and we can discuss that in place - we will all save the intermediate steps of writing here and can merge the change quickly. Documentation should be easy enough to change to obviate most issues. But I’d be happy to include a template if you have a proposal.

The nix.dev public contribution guide is transcluded into the website. Update it directly.

toraritte · July 19, 2022, 12:33pm

@fricklerhandwerk Thank you for the comments!

It would be very helpful to have dedicated issues tagged with documentation for these things, tagged appropriately (ping me so I can add tags).

This was more like a braindump to be organized, before I haphazardly open issues to multiple repos that not even I’ll be able to track anymore…