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.
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.
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.
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.
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.
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…
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…
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.
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.
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.
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.
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.)
I’d like to revisit this topic with a new proposal. The GitBook system seems quite attractive.
It’s a cloud service with hosting, decent search, and a nice WYSIWYG editor that can be used directly on the pages themselves with just a GitHub (linked) account. The backend is proprietary, but syncs to a bunch of markdown files in the GitHub repo. Edits can also be made to those markdown files and are then directly visible on the web.
Using this would buy us a few advantages:
Users can edit the documentation WYSIWYG on the documentation site, instead of having to learn the fairly arcane RST format and make a pull request. (This requires people to sign up / sign in on GitBook and be given permission. I’m not sure exactly how that flow works.)
Anyone can still edit the “source” in the form of markdown files in the repo. Markdown is, admittedly, a little less expressive than RST. It’s also easier to deal with…
With the docs in the main repo, the web rendering picks up the current version from tags and you can switch between branches to see docs for older versions. At the same time, docs changes can be done at the same time as code changes, if you’re a dev.
The graphical design is somewhat more up to date than our current one.
The search actually seems to work.
Certainly there are some downsides too:
We need to convert from RST to markdown. For many pages this is trivial, but requires some manual hands on as well.
We need to tweak the process to generate man pages from the new docs. This is doable.
It’s a random cloud service that might go bust at any time. But they have a few large users, and we have a structure of markdown files in our repo, so worst come to worst this is trivial to again generate a static site from.
I added a proof of concept at https://gb.syncthing.net/ with just a couple of pages converted (i.e., most of the links still point back to docs.s.n.). It syncs to my syncthing fork repo.
Changes done on the web show up as meaningless but mostly harmless commits in the repo, like this. It’s no worse than what happens with the edit-on-GitHub option today (which is also still available, for that matter). Arguably better as it at least has a commit prefix where the GitHub default is just “Updated foo.md”.
Main points I see as advantagaeous is getting a WYSIWYG editor instead of RST in front of people, and getting the code and docs in sync version wise.
I think everything that increases the chances for documentation being written is good. I haven looked at the tool yet, because as when I try to join via the link, I get get greeted by this nicely translated message:
On github we can change it on merge and GitBook: [master] one page modified is quite crappy - I mean of course something was modified, otherwise there wouldn’t be a commit, but what is modified (filename or something at least). However I agree that’s not a showstopper.
How is the review process going to look like? Still github PR or directly done on that external site.
I agree on the commit messages. There’s a thing in the edit GUI where one can enter a change description, which I’d imagine becomes the commit message. It doesn’t, though, so that sucks.
Access wise, once you are added on GitBook you can just hit edit, save, publish and it will push to GitHub with a bot. This bot would need push access and it wouldn’t go through a PR.
But this requires being added to the organization on GitBook itself separately from GitHub, so it’s not really as casual as I’d maybe hoped. In fact the “edit on GitHub” link instead takes you to the file on GitHub as usual, and the edit flow from there would be the same as currently. So there’d be both ways, with the WYSIWYG one being less accessible to new users.
(That said, I think most new users will still have an easier time with markdown than rst. Even I hardly know how to make a link or monospace text after all this time and need to look it up by example.)
There’s also the thing that hints and warnings that are easy to do in the GUI become somewhat ugly {% hint style="danger" %} foo {% endhint %} things that I’m sure other markdown parsers will barf on…
All in all I like the rendering but I’m not sure it’s as awesome as I thought. Still, it’s no worse than a static site generated from the repo, and it still has neat things like version selection based on branches.
You can’t join, because the Syncthing organization is currently on “Free”, which only allows 2 users. We need “Startup” for unlimited, which is free for open source projects.
I don’t really like this, it essentially means you trust a user entirely (direct push access) or you don’t trust him at all (no invite). There have been good new user contributions, but they often needed tweaking and sometimes even had some minor misconceptions in them.
