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

[Felipe Augusto van de Wiel <felipe.wiel@hpp.org.br>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Hi

On 05-07-2012 17:30, Jan-Piet Mens wrote:
>> 1. 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.


[...]
>> 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>

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?


[...]
>> 4. 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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQIcBAEBCgAGBQJP9h7XAAoJECCPPxLgxLxPKT4P/iOktocbskgVW6HQDxB8OkL+
SKqKrZCsJ8gyh1nziQTBSuIJmn+z8GC3YmqbN+icv7SGbgwB99IhCmILN+wV10sD
LCxeS3Gg2XoIPNwh/nlT86hiSzKjfS6McsoPEIF8R3fjwQvDh2FoofqLzrCmVzwR
iTRgJBKrV0IEbaQIvX8oGa2F4L7G58a4KptgrDdwaX1PlnABIgOohCGbWe6/WRCS
tofDhfsvc5WB0EQQyLcZfXu6shM29aJRrfYNaEVPRb5rOZqSGLl0OEdr+GS8DPFv
4fI2/aQkd1qHev36oGGe0XujlcthkNDA9BKZh+1SxZtUb+4K8GsDsvnIOMnq3mLv
QgziiHsHVwfrehcXUsw7vzjfYwIvLSQV9pmGeP34JIlMGM5l6MvgP3kAfTGPmO3U
YYDP9QH9deNHzDCTo4z/szdKpCWjdIQ6iWZHXCFYSMWHxBDDOpERJ6Ok5hh+BB1+
Cm3jEmVi9GT1Br9CcpcFJABPcpj5vYNC5/wJLMV5PTQE4HUQ9wTrTfxZslt2yaVe
8QdWcObTkZFY16PJjtH0l7Z6uGQsbc2cqam5brKRHpVMvSTxncjjnsj88vUtVQvL
LN9RmVK8ZhCaV7PoUGMu0OjR+/3CX6v155RnRxEMWX6Tk+jov7ODmZ+ZNvpFelBP
qs4MN5j/o3Y3MJvem3cL
=QLy8
-----END PGP SIGNATURE-----