I get what you are saying about over-forking being a problem, and I see how rdoc.info could maintain its own forks (I suppose these would live in the github.com/docs account we have setup).

In terms of opensourcing… we did it from day one :) http://github.com/zapnap/rdocinfo. Fork away and implement this feature! ;)

When you go to the docs for a repository, you see the *latest possible version*, regardless where it came from. If that's the owner's latest commit, you see that. If it's a wiki edit after that latest owner commit, you see the wiki version. That's the “which version to display by default” thing.

The “no-hostages” thing is the opposite of what you thought. When the owner commits something, *that* becomes the latest version. The previous wiki edit is moved to the history, and the owner's version is displayed (which is the same as saying that, in the merge, all conflicts are resolved *in favor of the owner*.)

Of course that, for repositories that were put in rdoc.info by someone other than the owner, it would be frustrating for wiki editors to see their changes being clobbered by commits from the oblivious owner all the time (even though still recoverable from the history). That's why I suggested that wiki editing be opt-in by the owner.

One problem with the workflow you suggested is that it creates a multi-headed wiki, without a clear linear history. And if you don't show the latest edit immediately (instead waiting before the owner folds them in), there's a higher chance that people will step on each other's toes, fixing the same typo or editing the same line multiple times. The longer feedback cycle makes conflicts more likely and integration more difficult. Worse than that, the workflow is incompatible with the way rdoc.info tracks documentation.

Rdoc.info tracks documentation *per-fork*, independently. Take http://rdoc.info/projects/search?q=delayed_job, for example. I keep a fork of delayed_job because I have a feature there that is not present in other forks. According to your workflow, if I edit the docs for helder-delayed_job to describe my feature, collectiveidea and tobi are going to get pull requests for that change, which doesn't make sense. And if I want to edit *their* docs (maybe I found a typo in the docs for a feature they have and I don't), that change will be committed to *my* fork, which doesn't make sense either. Also, this workflow requires that a user have a github account and fork the repository just to make a simple edit. Unnecessary forking polutes the network and your fork list — I'd rather have forks only for projects I'm doing significant contributions to.

What we need is one linear (centralized) doc history *per fork*. So you'd have separate doc histories for helder-delayed_job and tobi-delayed_job, etc, which everyone could individually edit without needing to fork it themselves, or without affecting their own fork in case they had one.

My original idea actually falls short here as well, as the rdoc.info user can't fork different repositories *of the same project*. So patch my idea with:
-Rdoc.info forks your repository and commits every wiki edit to that fork.
+Rdoc.info forks your repository (if it hasn't already), *creates a branch to track your fork* (named, say, “helder-docs”) and commits every wiki edit to that branch.

So if I go to the docs for tobi-delayed_job, what I'm seeing and editing is always the head of the tobi-docs branch in rdoc.info's fork of delayed_job (github.com/docs/delayed_job/tree/tobi-docs).

If it's the docs for my own fork, edits go to helder/delayed_job/docs, which gets picked up by rdoc.info and merged back into docs/delayed_job/helder-docs.

I don't know if I made this sound too confusing, but it's actually quite simple :) We can schedule a skype talk if you want so I can explain this better (I'm obvio171).

Btw, do you guys consider opensourcing rdoc.info? ;)

In our version, instead of maintaining a separate branch you do exactly what github encourages you to do and maintain a separate fork (which is just an ad-hoc kind of branching). When you make a change, we should do the following:

(1) If you a committer on the project (or owner): automatically commit the change that you make to the wiki style interface. This is the easiest thing.

(2) If you not a committer: fork the repo, but not as the rdoc.info user… as the current user (we will need to connect the github user to the rdoc.info user). Then make the commit to that fork and redirect from the current docs view to the users new forked version of the docs (which we auto-generate). Send a pull request.

(3) Modify the interface to list related forks, revisions, and tags. This is planned already, but would become pretty important.

Does that workflow make sense?

It still doesn't cover some classes of edits like correcting typos, grammar, reorganizing text to improve how it's structured, and rewriting parts to improve clarity. Notes basically add coverage, but don't improve quality.

Opensourcing APIdock is great news! I haven't been following it too closely, so I hadn't heard of this. The whole auto-fork thing needed to implement wiki editing is indeed not trivial, but I think it would be a great thing to have.

And new changes would be instantly visible. The latest owner version will still be reachable from the history, and you can make it somehow visible to the visitor if they're seeing a page with changes that weren't yet folded in, linking to the latest pristine copy.

When we were initially writing APIdock, having the wiki-style editing seemed like core functionality. However, after we had run the site for a while, it occured to me that wiki-editing doesn't actually solve the problem.

The #1 priority is to lower the barrier of contributing – and that's exactly what user-generated notes are good at. However, many of them are not directly ready to be used in official documentation.

So far it has been easier to pick the good stuff from notes and commit it to lifo's docrails Git repository. We're hoping to improve this in the future.

There are some plans about opensourcing APIdock, so theoretically it would be possible for anyone to add the wiki editing functionality. But still, I don't think it would be so much better than simply committing to docrails.