[Koha-devel] Lets improve the Koha installation documentation

[Mason James]

On 2012-08-28, at 8:18 AM, Mason James wrote:

> 
> On 2012-08-24, at 7:27 AM, Robin Sheat wrote:
> 
>> Op 23-08-12 21:00, Mason James schreef:
>>> there looks to be some good conversion tools between asciidoc, pod, and wiki
>>> (and then html, docbook, pdf and latex too)
>> 
>> While you're exploring, I hear good things about markdown as a
>> human-writable but still parseable format, and I'd give good odds
>> there's a markdown to mediawiki converter.
> 
> i've just discovered the 'pandoc' tool, which looks like it does every conversion possible :)
> 
> http://johnmacfarlane.net/pandoc/
> http://packages.debian.org/squeeze/pandoc
> 
> 
> i'll get some tests sorted this week, for the various doc formats. 
> 
> stay tuned…


ok, so a little late... but some very successful news… :)


I've managed to sort some *automated* steps to convert the installation-docs on kc.org wiki, to many various doc formats...
i spent some time experimenting with the big 3 formats - RST, markdown and asciidoc
(all 3 were very nice, cheers!)

after a process of elimination, RST was a pretty clear winner, why? 

1/ asciidoc has some import problems with pandoc (i.e.: its not currently supported)
2/ RST integrates tightly with sphinx, so HTML generated with RST is prettier than markdown


as examples, i've converted 2 docs from the kc.org wiki to RST

so these 2 wiki docs...
 http://wiki.koha-community.org/wiki/Debian
 http://wiki.koha-community.org/wiki/Koha_on_Ubuntu

convert to these 2 RST docs...
 http://pub.kohaaloha.com/kohadocs-sphinx/debian.html
 http://pub.kohaaloha.com/kohadocs-sphinx/ubuntu.html


then, using RST and pandoc, we can convert the docs to almost any format needed
 (take a look at all those output formats :) -> http://johnmacfarlane.net/pandoc/ )


as a nice bonus with RST, we also get to convert the Koha manual (docbook/xml) to RST/sphinx too

so, from this...
 http://manual.koha-community.org/3.10/en/administration.html

to this...
 http://pub.kohaaloha.com/kohadocs-sphinx/man.html


finally... I'm volunteering to be Koha's 'installation doumentation' manager 
a new role, similar to Nicole's 'documentation manager' role, but focusing on Koha's installation documentation only



http://en.wikipedia.org/wiki/ReStructuredText
http://en.wikipedia.org/wiki/Markdown
http://en.wikipedia.org/wiki/Asciidoc
http://sphinx.pocoo.org/contents.html