http://qs321.pair.com?node_id=245907

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:

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-

Replies are listed 'Best First'.
Re: POD as a general documentation system
by PodMaster (Abbot) on Mar 26, 2003 at 13:13 UTC
    I use pod as a general documentation language :)
    I document (lately) my java in pod (javadoc--) :)
    I take notes in pod (always!) ;)
    I write essays in pod (not that I care to share).

    How the mind works (association) is a part of it, but I'll bet another part is exposure. Most people just haven't a clue what pod is, or it doesn't seem appealing enough. Here's what they may be thinking:

    • How do you embed images in POD? they'd ask
      • What? No Images?? they'd say, to which i'd respond:

        Most documentation needs no images (even though there is plenty of users who might prefer it), so most writing documentation don't mind (i sure as feck don't), and neither should you (plain is plenty). But if you're desperate, you can always embed html (as in =begin html html =end html).

      • What? =begin html?? they'd say, to which i'd respond:

        It may seem weird to embed other formats into pod, but that's the beauty of pod. You may argue why not use html to begin with, but you know why. And if you don't like doing it because you have more than one target format like html, well you got Pod::Parser (among many others) baby, so invent your own ( =for imageEmbedderInAllMyTargetFormats filename anybody? powerful indeed).

    MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
    I run a Win32 PPM repository for perl 5.6x+5.8x. I take requests.
    ** The Third rule of perl club is a statement of fact: pod is sexy.

[reply]
[d/l]
      Most documentation needs no images
       Indeed. I used to think that images were necessary in documentation (after all, an image speaks for 1000 words), but I dropped this off my list of requirements when I noticed that the vast majority of my stuff does without them. So, it's not on my requirements list, and if I really need to include an image in POD, there's always =for formatter as you say.

      Thanks for your comment!

      CU
      Robartes-

[reply]
[d/l]

        Robartes,

        As a sysman you probably do not need to include a lot of images in your documentation, but that doesn't necessarily mean POD is versatile enough to be an all-round documentation system, IMHO.

        Technical analysis of programs for one, benefits a lot from pictures and diagrams. (At least in my experience)

        Nevertheless, I can fully agree with you: POD offers a lot of possibilities.

        Cheers,
        MichaelD.

[reply]
      On the text versus image topic philosophers of language would claim that the ultimate goal of philosophy is the analysis of a thought; thought studies have to be separate from psychological thinking processes and the only proper method of thought analysis is through language. If we'd take a radical stand, images hardly belong to the language; so here we go - the ultimate text world ...
[reply]
      The lack if images and basic tables really is a problem. I have written articles for perl.com in POD. I often need to represent something with a graph or a table of data, and this is basically impossible in "pure" POD. I think I may switch to a very limited subset of HTML at some point.
[reply]
Re: POD as a general documentation system
by Abigail-II (Bishop) on Mar 26, 2003 at 14:41 UTC
    I've used POD as documentation. I've used HTML as documentation. I've used *roff as documentation. I've used LaTeX as documentation. I've used PDF as documentation. I still use the latter if I need to write something for a customer and it needs to look "fancy" (I write it in LaTeX, and translate the dvi to PDF).

    But nowadays, I swear by plain ASCII documents. It's the only true platform independent format (yeah, there are non-ASCII platforms out there). Anyone can read it. Anyone can edit it. And just before you think "plain ASCII sucks, I need markup/images/whatever", realize that RFCs have been written in plain ASCII for more than 3 decades, and will be written in plain ASCII for quite some time. I can read RFC 1 (which was written in 1969 and contains "images") as easily as the newest RFC.

    Plain ASCII rocks.

    Abigail

[reply]

      Plain ASCII rocks.

      Yes, plain ASCII rocks. But one of the beauties of POD is that it is so easy to convert.

      POD is easier to write than plain ASCII documentation, if you want the same features. Although I don't use images in my documentation, I do use definition lists. POD makes creating a definition list very easy.

      And when I'm done, I pod2text my document. But I can also pod2html and put it on my website with nice markup.

      Anyone can read it.

      Anyone can read pod2text's output

      Anyone can edit it.

      If someone is uncapable of editing POD, that someone is VERY stupid.

      You don't have to learn anything before you can edit plain text. Or do you? Is indenting done with tabs or spaces? Do we use 72, 78, 80 or 40 characters per line? Or do we think of lines as paragraphs, and let the pager do the wrapping? How are lists layed out?

      With POD, it's much easier to have a consistently layed out document

      "images"

      I like POD's verbatim paragraphs :) 

      Juerd
- http://juerd.nl/
- spamcollector_perlmonks@juerd.nl (do not use).

[reply]
        "...Yes, plain ASCII rocks. But one of the beauties of POD is that it is so easy to convert..."

        I'll second that. I have often been tempted by complex markup languages until I came across Stas Beckmans site (stason.org) after attending a local pm about the upcoming Mod_Perl 2.

        All the documentation was available simultaneously in printable PDF (see the top RH icons) and viewable online via html and in Perl itself. For those that are interested it is processed using docset, Pod::HtmlPsPdf etc.

        And all editable via POD.
[reply]
      If I could have ++'ed a node multiple times, Abigail, you would have gotten all of mine for the day.

      enoch
[reply]
[d/l]

      You could read RFC 1 just as well if it was written as POD.

      POD has hardly changed during the last 2 decades as well, right?

      And the little bit of markup introduced by POD allows one to make the document navigatable by means other than scrolling and searching for patterns.

      Metadata rocks. POD keeps the difference between marked up text and plain ASCII very minimal. POD rocks.

      Makeshifts last the longest.

[reply]
        POD has hardly changed during the last 2 decades as well, right?

        POD didn't even exist 2 decades ago. In fact, POD is less than a decade old, it came with perl5. And, given what's going to happen with perl6, I wouldn't want to bet money on "POD will not change the next decade".

        Besides, all POD tools are written in Perl. Having to install a dinosaur like Perl just to be able to deal with general documentation doesn't rock - it sucks. It's hardly any worse than requiring people to install Word or some other tool that reads Word format.

        Abigail

[reply]
Re: POD as a general documentation system
by zengargoyle (Deacon) on Mar 26, 2003 at 13:19 UTC
[reply]
Re: POD as a general documentation system
by jand (Friar) on Mar 26, 2003 at 21:22 UTC
    I used to use POD for all kinds of documents. But I was never quite satisfied that POD still has a lot of ugly markup. I guess some may consider this a sacrilege, but I think reStructuredText is both easier to read in pure ASCII form and is more expressive when translated to HTML (yes, you do need a Python interpreter to convert reST to HTML).

    I still use POD for everything related to documenting Perl code, but use reST for things like functional specs.

[reply]
Re: POD as a general documentation system
by nite_man (Deacon) on Mar 26, 2003 at 14:43 UTC
    In my mind, POD is good solution for documentation your modules and scripts (however, I would prefer some like javadoc)
    If it needs to create some project documentation or write an article, I would advise docbook as a good tool because it is very useful and powerful solution which accumulates the best traits of previous systems. 
       
-------->
SV* sv_bless(SV* sv, HV* stash);

    [download]
[reply]
[d/l]
Re: POD as a general documentation system
by gmpassos (Priest) on Mar 27, 2003 at 03:39 UTC
    POS is very good because is easy and fast to do (KISS), not more hard than a comment. And you can convert it to any format, and have good looks too.

    I don't like for example the JavaDoc style, that you can see in java.sun.com. I think that Java has many things to learn with Perl. For example, to understand how a class work in Perl is very easy, but in JavaDocs you need to open a lot of pages. Java always think in OO, but the docs don't help much the OO idea.

    Graciliano M. P.
    "The creativity is the expression of the liberty".

[reply]
Re: POD as a general documentation system
by palindrome (Beadle) on Mar 28, 2003 at 00:27 UTC
    I too have tried various formats/markups over the years when creating customer documentation.

    These days, I "write" much of my system documentation with a few, well-worn scripts. I find POD markup very easy to programatically generate, and conversion to other formats just couldn't be easier.

    And you know, it even looks good when I <horrors> munge it into an MS Word doc for my corporate clients!

    Palindrome-a-day: U.F.O. Tofu!

[reply]
Re: POD as a general documentation system
by Pardus (Pilgrim) on Mar 27, 2003 at 11:59 UTC
    The one thing I miss the most in POD is a way to create structured indices. Of course I now do that with a =begin html ... =end html but when converting to some other format, the index is gone.
    --
    Jaap Karssenberg || Pardus (Larus)? <pardus@cpan.org>
    >>>> Zoidberg: So many memories, so many strange fluids gushing out of patients' bodies.... <<<<
[reply]
[d/l]

Back to Meditations