I was actually doing some thinking on what I'd like to see in the process and it mostly comes down to 1) automating POD creation but still making a POD that has touches of a human element and 2) coming up with a great README file based on context (one for GitHub and one for CPAN).

In fact, I started writing up a rough idea of what would go into an ideal README file. It would be something like this: 

OVERVIEW

This software code, written in the Perl programming language, <%SUMMAR
+Y OF MODULE IN 1/2 SENTENCE IN AS NON-TECHNICAL LANGUAGE AS POSSIBLE 
+%> 

WHO IS IT FOR?

The target audience for this software is <% DESCRIBE WHO A TYPICAL USE
+R MIGHT BE %> who is trying to <% DESCRIBE THE PROBLEM TRYING TO BE S
+OLVED %>

IS THIS SOFTWARE CURRENTLY MAINTAINED?

This software is in an <% EARLY|ACTIVE|INACTIVE %> state of developmen
+t <% AND|BUT %> is considered to be <% EXPERIMENTAL|UNSTABLE|MATURE %
+>.

Bug reports are <% LARGELY IGNORED|ACTIVELY RESPONDED TO %>. To learn 
+how to report bugs, see the BUG REPORTING section on the man page at 
+<% LINK TO BUG REPORTING SECTION ON MAN PAGE %>

IS THIS SOFTWARE EASY TO USE?

<% OVERVIEW OF SKILLS & EXPERIENCE NEEDED OR EXPECTED %>

HOW DOES IT WORK?

Please see the man page at <% LINK TO MAN PAGE %> for how to use this 
+software.

IS THIS PROJECT ACTIVELY LOOKING FOR HELP?

This project <% IS|IS NOT %> seeking assistance from other developers 
+at this time. Pull requests and other contributions <% WILL|WILL NOT 
+%> likely get ignored.

<% BULLET LIST AREAS WHERE PROJECT COULD NEED HELP HERE %>

Please consult the man page at <% LINK TO MAN PAGE AND OTHER RESOURCES
+ %> if you would like to get involved.

HOW DO I GET IT INSTALLED?

Please, follow the instructions at <% LOCATION OF INSTALLATION GUIDE %
+>

OTHER INFO

Copyright, authorship, and basic license can go here.

[download]

I want to be able to easily generate a README file similar to that quickly and easily. Probably just a simple templating solution is all I need. Dist::Zilla can do that but it's been a little rough figuring out the best way to actually execute it.

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

In reply to Re^2: What are your best practice recommendations for maintaining CPAN module with GitHub repo? by nysus
in thread What are your best practice recommendations for maintaining CPAN module with GitHub repo? by nysus

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.