As a system administrator and system engineer working for various customers, I tend to produce lots of documentation, ranging from installation documents over fix documentation to detailed procedure descriptions of various things. Over the years, I have used straight text files, HTML, Docbook SGML and XML, LaTeXand Lyx for this, and probably some more formats I have forgotten by now.

Using all of this, I've come to appreciate that my requirements for a documentation system are:

• Documents should be editable in a straight text editor.
• The system should be able to generate output in a number of open formats, including HTML, PDF and straight text.
• Simple markup should be present.
• Markup must not get in the way of content. There should be more content than markup.
• The system must be versatile enough to handle different documentation types.

Most of the stuff I have tried fails on one or more of these requirements. Straight text does not have markup, Docbook fails on the markup vs content requirement, HTML is borderline on that requirement, and LaTeX and Lyx are a bit too far out of my cultural playground.

Lately, however, I have been using good old POD for my documentation purposes. I can use a text editor to write it, it can be converted to text, Unix man pages, HTML, and various typesetting formats, including PDF (and if I want another format, it's easy to roll your own based on Pod::Parser). There is markup present, but it does its best to stay out of the way of content. And versatility is more an issue of how you write your docs than what you write them with.

Despite this, and for some unknown reason, it never occured to me to use POD as a general documentation system, as opposed to documenting just Perl scrips and modules with it. Maybe this is because most of the POD documentation mentions POD in this context only, or it is because of the way the human mind works: once POD is connected to Perl in your mind, it tends to only be associated with it until the proverbial lightning strikes and you are able to take a step back and oversee the woods you were unable to see before because of the trees (how's that for mixing metaphors <g>).

But, now I've seen the light and I'm happy to say that so far I've found POD to be fully sufficient for my day to day documentation needs. POD might have been designed to document Perl code, but it is equally good as a general documentation language. It is Plain Old Documentation after all!

What's the monks opinion on this? Is there anyone else who uses POD as a general documentation language? Apart from writing the Camel book? <g>

CU
Robartes-