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.