Divergence between wiki and source-tree docs

I'm agree, because this open up more room for documentation cotributors, and even simplify process of docs translations (and include translated versions to distribution).

I want to little proposal: at firts implement python script to automate process of copying the latest versions of the wiki documents into the source tree, and provide coorect way to handle situation when wiki-source not in RSTX format. Just to be sure docs update never fails horribly. And then convert all corresponding wiki-pages to RTSX format.

To implement 3 I propose to create new target in Makefile:
make update-docs

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.

I think this is much less of an issue now that the official doc site is easier to navigate. As we come across old docs on the Wiki, we should replace them with a link to the official docs but I don't think we need to keep a bug open for that task.