[Date Prev][Date Next] [Chronological] [Thread] [Top]

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



Gavin Henry wrote:
> On 5 July 2012 16:44, Gavin Henry <gavin.henry@gmail.com> wrote:
>> On 5 July 2012 08:23, Michael Ströder <michael@stroeder.com> wrote:
>>> xsun wrote:
>>>> I don't remember if we talked about a wiki in the past but it's definitely a
>>>> good idea.
>>>
>>> While Wikis seem to be attractive at first glance the biggest caveat is that
>>> you can't cut a doc release of all the pages for a certain software release.
>>>
>>> In other open source projects which have all the docs in a Wiki this turned
>>> out to be a major issue.
> 
> Good point. We would just need to decide what docs go in the Wiki and
> what format we export them as for the guide.

To add more:

1. It's IMO better to commit doc changes along with code changes if possible.
I think this is already done with man pages. 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. And I guess only Kurt updates the content every now
and then.

This shows that maintaining/using the content over time is the really hard
thing no matter which media is used:

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.

Users have to be pointed to docs in a friendly manner every time it's
appropriate. Otherwise its existence is not known. When doing the OpenLDAP
booth at the Linuxtag years ago the most important thing was a printed flyer
with URLs to the various official OpenLDAP docs (admins guide and FAQ-O-MATIC)
we handed out to the visitors asking questions.

3. In several customer projects I had to use project/corporate wikis or I
tried to search relevant information in a project/corporate wiki. Even though
there were skilled technical writers creating templates and wiki structure
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.

4. Editing wiki pages cannot be done while being off-line during travel...

etc.

Ciao, Michael.

Attachment: smime.p7s
Description: S/MIME Cryptographic Signature