Move docs to main repo?


(Jakob Borg) #1

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.

Discuss.


(Audrius Butkevicius) #2

My gut says no. Lockstep is a developers problem, which we have much less of than potential docs contributors. Also blending the issues together will be a nightmare.


(xor-gate) #3

I’m a big fan of moving docs into main repo, this keeps it tightly coupled when changes are made and documentation is updated in one step. Which in turn gets the benefit of less overhead and more traceability of feature/change in a single merge doc <-> code.

For the point @AudriusButkevicius gives, you can manage it with correct labeling IMHO. If you look at the golang project main repo on github it has a huge issue tracker which is easy to navigate. And it also contains sourcecode and doc in one repo https://github.com/golang/go/tree/master/doc.

As @calmh mentions the issue tracker of the docs repo catches less dust then combine docs into main.

For the point documentation writers need the same flow as for code writers I’m a big fan to have one unified process to get things into mainline. Instead of making two different contribution flows.