Add “suggest edit” and comments/discussions features in NixOS.org Manuals


#1

I touched on this in this discussion. But though it would be better served as it’s own conversation.

I feel that contributing to manuals/documentation is at times too laborious. I understand the desire to do everything using Nix, but I think it would be to everyone’s benefit to make it easier to add notes/suggest edits to the NixOs manuals online. Frankly forking nixpkgs, rebuilding the docs, making a pull request, etc is such a barrier to make contributions. This has personally kept me from ever adding to the manual, and I would wager that I am not alone here. Especially because if I do make a pull request I feel that my suggestions need to be “bulletproof”, and if they aren’t, they are unlikely to attract refinements sitting around the “pull requests” tab on GitHub.

Quite often I will find some things outdated, or not quite suited to what I was trying to do, sparse documentation, etc. After I find solutions on my own, or with help from the IRC, I sometimes post them here on Discourse; but they would be much more accessible to others on NixOS.org.

In practice these could look like drop down “discussion” elements for sections of the longer manuals, or footer sections on shorter single page discussions. They could be cleanly collapsed away, or even remain unloaded until someone expands them.
As they grow we can periodically move the most helpful notes into the manual itself. I imagine this would be a much more organic and convenient way to build these than someone sitting down every few months to overhaul sections of the manual as a “project”.

If this seems like a worthwhile addition I would be more than happy to help implement it.


#2

In practice these could look like drop down “discussion” elements for sections of the longer manuals, or footer sections on shorter single page discussions. They could be cleanly collapsed away, or even remain unloaded until someone expands them.
As they grow we can periodically move the most helpful notes into the manual itself. I imagine this would be a much more organic and convenient way to build these than someone sitting down every few months to overhaul sections of the manual as a “project”.

Given that NixOS Wiki already exists and has a team that does good work maintaining it, maybe what you want is some kind of better interaction between Wiki and Manual?


#3

The wiki was exactly what I was looking for. Thank you!
I know I have bumped into it a few times but I guess that visual similarity to the manual made me think that these wiki pages were somehow connected to that actual manual?

It would be nice to get that pagerank up; I’ve only bumped into these wiki articles a handful of times.
I will definitely start posting there from now on.

Thanks!