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