Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
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>


In reply to POD as a general documentation system by robartes

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others contemplating the Monastery: (4)
    As of 2017-12-17 11:00 GMT
    Find Nodes?
      Voting Booth?
      What programming language do you hate the most?

      Results (463 votes). Check out past polls.