Divergence between wiki and source-tree docs

[Alexander Belchenko]

Proposal from Aaron Bentley:

I think we should fix the divergence between wiki and source-tree docs.
 I think it's a good idea to retain the wiki version as the primary
version, because it is easier to update.

Here's what I suggest:
1. switch the wiki versions of the documents to ReST
2. automate the process of copying the latest versions of the wiki
   documents into the source tree
3. make updating the source-tree documents part of the release process

[Alexander Belchenko (bialix)]

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

[Ian Clatworthy (ian-clatworthy)]

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.

[Ian Clatworthy (ian-clatworthy)]

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.