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.


(Jakob Borg) #4

So one for, one against. Anyone else have an opinion? (“I don’t care” is also a valid opinion here I think.)


(Simon) #5

I am kind of undecided. As in I think it would be good to have changes coupled to documentation. But then we actually need to enforce doc updates on PR level, otherwise it’s a zero-sum-game. And that means additional work for coders and thus a bigger entry barrier. On the other hand, I think having more up-to-date docs would be very beneficial for the project. And it isn’t necessarily the case, that the code author also needs to author the docs. So in the end I am only in favor of adding docs to the main repo, if this move is accompanied with some kind of policy.


(xor-gate) #6

I think the policy could be enforced by only protecting branches by merges and review only to the baseline branches. So nothing will be directly committed.


(Jakob Borg) #7

That is essentially how it is today, but not how it is on the docs repo. This is what I meant with it becoming a stricter process than today, for those contributing docs.

I don’t think adding a few tens of issues to the main repo with the “docs” tag will result in any calamity we’re not already suffering under.

The primary reason I want to do it (or I wouldn’t have brought it up) is to make the docs less of an isolated and ignored island…

Current protection settings:

I would have liked to be able to relax some of the requirements for pushes only affecting, say, docs/, but GitHub doesn’t support that. That said, there are new options on this page that weren’t there a couple of months ago so they are adding functionality…


(Audrius Butkevicius) #8

So I still hate this idea that we will loose the ability for the community to self maintain docs, ans we will have to bless all docs prs. Also, it will be muddled where the docs actually are…

All of this for a theoretical epiphany where people update the docs with the code. I can tell you docs being in the same repo won’t mean I’ll start giving a shit for updating docs. This has to be done by PR reviewers, not by moving docs to a place its harder to find and govern.


(Jakob Borg) #9

My proposal includes adding all current documentation contributors to the org, so extending the relevant community accordingly. It still means a contribution needs one more person to do the blessing, but it doesn’t have to be you. I think there are enough people happy to do the blessing, but as it is there is limited attention on the docs repo today PRs end up stale.

If anything, I think the docs repo is the one that is harder to find than the main one.

But we may need to just agree to disagree on this one. I’m not barging ahead with it just yet. :slight_smile:


(xor-gate) #10

I’m trying to quote the post of @AudriusButkevicius but could not find the same way you have commented @calmh (missing knowledge of the forum probably.

But I agree on the govern point of @AudriusButkevicius. You could also close the issue tracker in the docs repo and let all issue go into the main repository. If you look at the golang.org/x libraries it is IMHO also handled in this way. E.g https://github.com/golang/net -> has issue in golang/go.

The main issue tracker for the net repository is located at https://github.com/golang/go/issues. Prefix your issue with “x/net:” in the subject line, so it is easy to find.


(Jakob Borg) #11

I don’t understand the “harder to govern” point so I didn’t respond to it. What does it mean?

(To quote stuff, select it - a “quote” button appears.)

I think another point for moving the docs into the main repo is that a certain subset of support-like issues that are created, and now just closed, are in fact legitimate “x should be [better] documented” issues.


(xor-gate) #12

Why not create a forum poll on the decision by the community instead of tossing coins :smiley:


(David) #13

I think a non-developer’s opinion (i.e., 98% of the users here) is less relevant to this question.


(Jakob Borg) #14

FWIW, this is the canonical example of a question that should have been answerable by diffing the relevant docs between two releases:

As it is I can git diff v0.14.43..v0.14.49 -- lib/config and get a feeling, but the changes are much more extensive than just the user facing stuff and harder to mentally aggregate. (I know, because I’ve done exactly this for a client.)