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. I mean, if available, we could start to migrate/review the content of openldap documentation page (AdminGuid, FAQ, etc) to the wiki.
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.
Gavin. -- http://www.suretecsystems.com/services/openldap/ http://www.surevoip.co.uk
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.
--On Thursday, July 05, 2012 9:57 PM +0200 Michael Ströder michael@stroeder.com wrote:
To add more:
- 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.
Definitely not true. I frequently reference http://www.openldap.org/faq/data/cache/1456.html on the mailing list. So often, in fact, that my browser bar returns it almost immediately when I type in the word faq. ;)
Also, I update articles there periodically, *and* it is in fact open to anyone for updating.
Also, the OpenLDAP project already has a wiki that is online. I don't think there is much on there at the moment though. ;)
--Quanah
--
Quanah Gibson-Mount Sr. Member of Technical Staff Zimbra, Inc A Division of VMware, Inc. -------------------- Zimbra :: the leader in open source messaging and collaboration
- 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
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512
Hi
On 05-07-2012 17:30, Jan-Piet Mens wrote:
- 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 sounds really nice.
[...]
- 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
- When was that page last updated?
- Search for, say, dynlist, on that page: only until OpenLDAP 2.3? Current version is 2.4
</rant>
It seems that the wiki sometimes work really great, you can find good info on Debian, Ubuntu, Arch and Dovecot wiki, while others are quite hard.
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
What would be the preferable form to contribute to docs? Patches? Editing FAQ?
[...]
- 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. :)
I'm not advocating pro-wiki, I'm really in pro of "whoever does the jobs pick the tools" and I do like wikis, but I do agree with a lot of concerns that were exposed on this thread. Anyway, I just want to spread the work about ikiwiki (a wiki compiler that uses git as its backend).
- From its website: http://ikiwiki.info/ Ikiwiki is a wiki compiler. It converts wiki pages into HTML pages suitable for publishing on a website. Ikiwiki stores pages and history in a revision control system such as Subversion or Git. There are many other features, including support for blogging, as well as a large array of plugins.
You can take a look at the features here: http://ikiwiki.info/features/
It uses MarkDown per default and generate static HTML (that can still be edited via web), uses very simple CSS layout (but is customizable). Even using git, you can still edit it thru the web interface, works very well and it might be what you are looking for, or might help building what you want. :)
Kind regards, - -- Felipe Augusto van de Wiel felipe.wiel@hpp.org.br Tecnologia da Informação (TI) - Complexo Pequeno Príncipe http://www.pequenoprincipe.org.br/ T: +55 41 3310 1747
Hi,
Michael Ströder schrieb (05.07.2012 21:57 Uhr):
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:
- 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. [...] 4. Editing wiki pages cannot be done while being off-line during travel...
Gavin already mentioned dokuwiki. And I think point 1. and 4. could be done by using dokuwiki with its plain text backend. http://www.dokuwiki.org/dokuwiki
Marc
openldap-technical@openldap.org
-
Felipe Augusto van de Wiel -
Gavin Henry -
Jan-Piet Mens -
Marc Patermann -
Michael Ströder -
Quanah Gibson-Mount