For detail documentation of software, I believe it works best to generate the documentation from the commented source code itself using a tool such as Doxygen (http://www.stack.nl/~dimitri/doxygen/ ). The result will be far more informative and more accurate and reliable with regard to the hard details than anything you would care to produce by hand, plus it can be kept automatically current with the current code base. The developer working on a file will have that file checked out already, so there is no necessary additional checkout/checkin burden to revise comments at the same time.

The weak point tends to be for more general themes and pieces of information that are not closely tied to specific actual code. To easily and readily tie all the details together with a larger general picture — perhaps that might be a place where a wiki could supplement the auto generated detail documentation.

The key then is tying the two together so that each can contribute what it does best. Using interwiki references (e.g. “this” for local reference) might be one way to do that.

In the above scenario, the wiki is used for more general or large picture aspects of the system that are not tied closely to the fast changing small details of the code. Those general pages could/should have a reasonably longer lifetime than the code and generated documentation that changes with each release.

Can anyone think of a better way to easily supplement autogenerated documentation than with an integrated wiki? Difficult/awkward procedures simply don’t get done.

Another quick-and-dirty way of approaching this is to create a Wiki hierarchy for each revision. For instance, /Ver1.x/DocPage1, then with new revisions, /Ver2.x/DocPage1. The TitleIndex could be used to establish of a list of exported pages, or the entire wiki could be exported to files. An initial version of documentation could be created for Ver2.x by using the pages for Rev1.x, doing some global search/replace and basic changes, then importing them under the Rev2.x hierarchy. Each revision starts out “clean” because there are no pages under that hierarchy at the start. (I’ve never actually done this, by the way.)

Another approach could be to have a “current documentation” area (/Doc/xxx or just /xxx), export those pages at each major revision, importing them under the pages for a specific revision (/Ver1.x/xxx), of course updating the internal page links along the way. You keep all revision history for the mainline documentation in that case, and start over for the archived copy. Somehow this makes better sense to me, since the active documentation is always at the same location.

For tutorials you usually want one person with a consistent style write it initially anyway. A wiki can help in that it allows anyone to write one without hassle and that people can correct grammar and factual misstakes as easily. A normal wiki probably do well for theese since there isn’t very many of them, just make sure to label each page with compatible versions, if you use namespaces for that(or “webs”) you can easily hack the wiki to allow “branching” and links to older versions.

That said, I am swayed by Ian’s argument and the fact that I’m about to have to do a global search and replace on the docs. Doing that with a through-the-web wiki is nasty to think about… doing that in TextMate is a pleasant thought.

The best bet may very well be to just go and keep the docs in Subversion, and to monitor the mailing list carefully to be sure that stuff that’s coming up there is landing, in some form, in the documentation.

You might do this by making a copy of all of the wiki documentation and moving it to its own wiki or area of the wiki. You might do this with an exported HTML / PDF. You could even doi it by exporting the content /into/ subversion.

I’d be curious to see a wiki with better integration with source control systems, though, I admit. But I’m pretty happy with Confluence, so it would take a compelling set of features to convince me.

http://www.edgewall.com/trac/

Yeah, maybe I’ve got the best setup as it is…

I played around with tools for this some time ago. Sadly, I’ve let the tools linger and break, not to mention the documentation built with the. Sigh. But generally speaking I think it is achievable.

As far as Wikis… well, textarea is the stupidest text editor ever made, and when producing serious documentation I consider it unacceptable. The whole environment is uncomfortable. And I don’t see Wikis producing good documentation. A few core people generally produce good documentation — sometimes in spite of a crappy Wiki editing interface, but not because of it — and external people add recipes and suggestions that provide important feedback. But you don’t need a Wiki to get feedback and comments.

I think a Subversion-based system, with a easy-to-run and easy-to write documentation testing system (maybe based on doctest, but maybe not) is the most important. Then a web browser of that documentation that allows comments and annotation — maybe just limited commenting on the (fairly copious) anchors that reST inserts automatically. Those comments could go in a companion file, maybe with a tool to merge them when you want to integrate comments into the documentation. Or maybe the comments could go into the document directly, especially if you can ignore them when testing (since there’s a security risk to testing documentation from a potentially anonymous source). I’m not sure what support reST can really provide for that kind of annotation; maybe a custom directive. But anyway, that’s my opinion on the matter. That’s a tool I’d like both as a user and as a developer/documentor.