Currently we have documentation in a repo that is separate from the main one. We do this for a couple of reasons.
- Access control (different crowds of people have access to each).
- Differing standards (that is, more lax requirements on things like commit message formatting).
There are at least a couple of downsides to this.
- There is no automatic connection between the program version and the documentation.
- Making changes to both code and docs in lockstep is a bit cumbersome.
- The issue tracker for the docs repo is a wasteland that no-one looks at or maintains.
What if we moved the docs into the main repo, and added all documentation writers to the main org (& AUTHORS?)?
- Better visibility for issues?
- Documentation kept more in sync with code, maybe?
- More credit given to documentation writers (this doesn’t follow automatically and could be done anyway, but I’d like to bring in and highlight doc writers equally as code writers; still leaves translators in the cold; might require redesigning the about box for practical reasons).
- Documentation writers subjected to a more rigorous (i.e., cumbersome) process (review required, for example, as we cannot disable this on a per directory basis).
- More people with access to the main repo, commits to master anyway require review so no huge risk of mistakes doing great damage.
- More people committing to the main repo, risking annoying @calmh by screwing up commit message standards.