[Pacemaker] Documentation challenge

[Florian Haas]

On 2009-10-19 11:58, Andrew Beekhof wrote:
> While I may be good at writing cluster software, I'm only average at
> documenting it and suck horribly at making pretty web pages.
> 
> Currently I use Pages.app (an Apple editor) for writing the docs because
> it looks reasonable and lets me focus on the content.
> However it uses an non-free format (preventing collaboration) and only
> produces PDFs while it seems people desperately want clickable html pages.
> 
> So, here's the deal...
> 
> If anyone can make
>    http://hg.clusterlabs.org/pacemaker/stable-1.0/rev/1111462a3d67
> 
> Look something even remotely like
>   
> http://www.clusterlabs.org/mediawiki/images/f/fb/Configuration_Explained.pdf
> 
> 
> Then I will start using docbook for the documentation.[1]
> 
> People that want a downloadable copy can have their PDFs, people that
> want clickable html on the website can have that too, and we can include
> an up-to-date version of either or both as part of each release.
> 
> And anyone that feels included can help make it better.
> 
> 
> Sound good?
> 
> 
> Key criteria are:
> - A style for commands such that they stand out from normal text
> (possibly a slightly thicker fixed-width font)

Put those blocks in either <programlisting> or <literallayout> with
<userinput> and <computeroutput>. Added bonus is that these preserve
whitespace (so you can kill all those ugly <para> elements). Making
these stand out is covered by my CSS -- which you already stole. :)

> - A style for XML blocks such that they stand out from normal text
> (fixed-width font with shaded background)

<programlisting>.

> - A style for output (fixed-width font with different shaded background
> to XML)

Either <programlisting> or <computeroutput>.

> - Professional looking tables, instead of ones that look like they're
> from 1995

For HTML this is pretty well covered. For FO is still sucks when using
fop as your FO-to-PDF processor. I tend to refrain from tables as much
as possible.

> - Captions that are centered and stand out from the normal text

<figure>, <equation>, <table> etc. all support <title>. <imageobject>
supports <caption>. Look at the Pacemaker chapter in the DRBD docs for
reference.

> [1] Remember how much you didn't writing a few dozen lines of
> configuration in XML?
> Consider how unenthusiastic I might be to write massive slabs of text
> with it ;-)
> The XML for "Configuration Explained" alone is 4700 un-wrapped lines long.

XML is a markup language, and it was created for documents, which it
remains infinitely better suited for than for configuration files (where
people really need to modify the markup -- it's perfectly OK to just use
XML as an internal config format and have a sensible front end to modify
it). So users do get to complain about having to hack markup. Tech
writers do not. :)

Cheers,
Florian

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 260 bytes
Desc: OpenPGP digital signature
URL: <https://lists.clusterlabs.org/pipermail/pacemaker/attachments/20091019/1634280c/attachment-0004.sig>