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