[Pacemaker] Documentation challenge

Andrew Beekhof andrew at beekhof.net
Mon Oct 19 09:58:41 UTC 2009


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)
- A style for XML blocks such that they stand out from normal text  
(fixed-width font with shaded background)
- A style for output (fixed-width font with different shaded  
background to XML)
- Professional looking tables, instead of ones that look like they're  
from 1995
- Captions that are centered and stand out from the normal text

I've made an initial export and conversion available at:
    http://dl.getdropbox.com/u/363965/html/index.html

You don't need to convert the whole document (but bonus points for  
anyone that does :-), just a small example so I can see the result and  
how to use it.

For the moment, I've stolen the css from DRBD... it looks a whole lot  
better than the defaults but nothing in there is sacred.
Also, you can ignore the fact that all the images are broken.

-- Andrew


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





More information about the Pacemaker mailing list