Best way to contribute to documentation?

Development Documentation
1

Reading the recent post Season of Docs (GSOC for documentation), I’d like to help out with documentation, since the lack thereof was the most difficult part for me personally switching to NixOS.

I’m not sure if I’m willing to do anything as formal as the Google Season of Docs; it’d be nice to contribute here and there as I grow my system configuration.

What’s the best way to contribute to documentation?

Should I help expand the NixOS wiki, or would it be better if I contribute to the more official NixOS manual?

Or maybe just post to #howto ?

What would help the community and newcomers the most?

1 Like
2

We are talking about it here already:

3

AFAIK we don’t have a Docs Leader. Also, we don’t have a docs dashboard/project/milestones. So all you can do now is follow Bazaar model and fix what you can.

There is ton of work on documentation (but first read why Docbook is still the tool of choice and how to stop worrying and love Docbook):

  • you can start fixing things you think were not clear for you
  • work on issues with tag needs: documentation
  • work on tags old: documentation and review issues with has: documentation. Unfortunately has: documentation often contains other changes
  • also, there are ideas to redesign manuals, you can throw your ideas as well

Ping me (@danbst) when you finish fix/review of PR, and I’ll do second review/merge. There are also other people willing to merge docs things - @domenkozar? @vcunat?

1 Like
4

Should I help expand the NixOS wiki, or would it be better if I contribute to the more official NixOS manual?

Intuitively, if you see a natural place in a manual, try contributing it there, otherwise start in Wiki and maybe ask people if it might be a part of a new subsection of the manual eventually.

Or maybe just post to Guides ?

What would help the community and newcomers the most?

What you searched first? No kidding — in a very real sense what you would prefer to have found might be more immediately useful for newcomers than what experienced people hope to eventually see.

(This probably also applies to form — of course, discussing whether the finer details are correct and not misleading can benefit from comparing the viewpoints of people with different levels of experience)

5

Imo the most approachable way is to add comments directly on Github.
This isnt a good idea for the manuals, which you should build; but for derivations its easy to add a few comments with the headache for forking the repo.

6

If you came here through a search engine, check https://nix.dev/contributing/documentation - that should answer most of the original questions.

1 Like