Dear Lazyweb,
I know of some software, and it has documentation. I want to be able to maintain this documentation, for the general good of its userbase. At the moment, its documentation is XML files in a VCS, with their own special build procedure with prerequisites. That makes them hard to modify, and as a consequence they are often out of date and certainly not as good as they could be.
Requirement A): I’d like the documentation to be web-editable, because that makes it really easy for anyone to edit quickly, which makes it much more likely the documentation will actually be up-to-date. I want the URL for the “latest version” to always be the same URL.
Requirement B): My software has multiple versions. Once I release a version, I’d like to keep a copy of the documentation in the state that it applies to that version. It may not change much again, but needs to be able to accept bug fixes. However, trunk documentation development must continue. In other words, I need to be able to branch the documentation, check in independently to each branch, and give people URLs to either a branch or the trunk. Each version should have a URL containing the software version number.
Is there any software out there, ideally already in use by the Mozilla project, which can meet both A) and B)? A) is met by all wiki software. B) is met by all version control software. But I haven’t found wiki software with the concept of branches, and I haven’t found a VCS which can display documents prettily and has a web-based interface for editing.
These requirements don’t seem uncommon. Proprietary software solves them. Is there anything open source?
Hatta doesn’t look very featureful, but should do the job.
http://hatta-wiki.org/
IkiWiki (http://ikiwiki.info/) is another wiki tool that has a wiki-front-end and a VCS back-end, although I don’t know how well it would suit that particular use-case.
I highly recommend ikiwiki. You can keep your documentation in the same repository as your software, safely let people edit the wiki via the web without letting them edit the code, and also accept contributions to the wiki via standard patches (even as part of the same patches that change code). You can also invoke ikiwiki when you build your software, to generate and ship a static HTML copy of the documentation.
http://gitit.net/
How about sumo? We designed to it display different content for different versions of Firefox as well as different OSes.
In MediaWiki, “namespaces” are the analog to “spaces” in the proprietary software you linked to. So in theory, it should be possible to create separate MW namespaces for different software versions, similar to what’s described in that article. That said, I don’t know off-hand of any projects that actually do that (a testament to my ignorance more than anything else). Another thing you might want to use namespaces for is various translations of the documentation. But then [languages * versions] could start to get large and unmanageable.
Alternatively, many projects are now storing and presenting documentation on github (for example https://github.com/bebraw/jswiki/wiki). It can be edited in the browser, or by using tools and processes that are familiar to developers.