About five years ago, I built a skeleton for Perl consisting of: 

#! /usr/local/bin/perl

package FILL-IN-THE-NAME;

use strict;
use warnings;

CODE-GOES-HERE

1;

__DATA__

=pod

=head1 NAME

=head1 SYNOPSIS

=head1 DESCRIPTION

=head1 EXAMPLES

=head1 AUTHOR

=cut

[download]
Basically, I took the format of the UNIX man() pages and added the 'EXAMPLES' header. In addition, I have occasionally added 'TODO', 'NOTES', or 'SEE ALSO' headers when they were warranted. As I write the code, I update the POD.

I did this for a project that had all the ear-marks of becoming humongous (due to a certain lack of detail in the specifications and requirements). I could see myself quickly losing what little mind I had left if I didn't take steps. So I cooked up the template and started using it religiously.

Six months into the mess, I (finally) got another body assigned to the project. She was somewhat boggled by the idea of doing the Doco as you went along, but she came around.

What convinced her was her first bi-weekly 'status review meeting' with the "Project Team". I wandered in with a hundred and thirty-five pages of printed POD and spent the next three hours answering questions with variations on a theme of: 'Yes, that has been implemented, and see page mumble for the Doc'; and 'No, we can't do that, it will break the interface to X, unless we do the following .... ". (I wrote a bit of code that generated an Index from the 'NAME' headers and a Quick-Ref from the 'SYNOPSIS' headers to pull this off.)

Over the next eighteen months that 'structured documentation' saved our bacon so many times....

----
I Go Back to Sleep, Now.

OGB

In reply to Re: POD Standards by Old_Gray_Bear
in thread POD Standards by ptum

Title:
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, details, 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, summary, 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.