- It's IMO better to commit doc changes along with code changes if possible.
I think this is already done with man pages.
Man pages are important and can be committed w/ the code, but that's not sufficient for most people, and yes: that includes /me sometimes too.
The one project I know that did a remarkable job of creating comittable documentation that went with the code is the Exim MTA [http://exim.org/docs.html] Philip Hazel, had some form of markup or other from which he generated HTML/PDF etc. with change-bars along the pages to point out what had changed in a release. Maybe take a look?
That's almost impossible with wiki pages. 2. The OpenLDAP FAQ-O-MATIC is kind of a wiki too. But nobody references its content on mailing lists.
<rant type="sorry about this">
Wikis suck. I think it was Michael who rightly pointed out there's typically no clean way to get good docs out of a Wiki.
The faq-o-matic sucks as well, and you're right: nobody mentions it on mailint-lists or anywhere else for that matter. Guess why? Sorry, and all that, but chosing a random page, say, http://www.openldap.org/faq/data/cache/1169.html
1. When was that page last updated? 2. Search for, say, dynlist, on that page: only until OpenLDAP 2.3? Current version is 2.4
</rant>
Besides Gavin and the core developers there are no others who continously contribute to the docs. While some people might argue that the cause is that there is no wiki I have some doubts.
+1
many wiki pages are outdated/incomplete very soon after they have been created. So even throwing lots of money on it does not necessarily help.
+1
- Editing wiki pages cannot be done while being off-line during travel...
Unless the "wiki-or-whatever-it-is" is in the git repo you take along and is closly coupled to the source. :)
-JP