Re: Docs To Do list and other ideas. Please contribute

[Jan-Piet Mens <jpmens.dns@gmail.com>]

> 1. 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

> 4. 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