Comment 2 for bug 89339

The divergence is a problem, e.g. the explanation of revision specs in the wiki is out of date vs the code currently. I'm sure there are plenty of more examples.

We definitely want tools to get the code and Wiki in sync but we might need to think a bit more about how to best do that. Using the Wiki as the master source has its pluses but I'm concerned how it would work for multiple versions/branches.

My gut feel on reference documentation (e.g. the embedded help) is that it is best maintained along with the code inside branches. As developers add new commands, new options, new values for options, etc., they ought to be enhancing and submitting the embedded doc as they change the code. The most important factor for the reference documentation is accuracy vs the code.

I'd like to see the Wiki used for maintaining Guides, one per release. "stable" & "development" might be the two releases initially. After 1.0 ships, we would need to leave older Guides around for users still on 1.0 say when 1.2 ships. Unlike reference material, guides are largely tutorial in nature. Accuracy is important but the more important aspect IMHO is quality of explanations. Those can nearly always be enhanced post-release so the Wiki approach can work better for them than doc inside a branch.