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

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

  • Comment on Re^2: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
  • Download Code

Replies are listed 'Best First'.
Re^3: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by stevieb (Canon) on Dec 18, 2017 at 22:29 UTC

    My README is usually just one of these:

    pod2readme lib/Main/Module.pm

    [download]

    ...but some do like to have a custom README that has different information. Because my distributions vary wildly as to what they do and intended target, I always write out my documentation manually, and keep a list of any methods or uses that I've changed, so I can update the docs before release. Things vary too wildly between the dists I write to really have any form of documentation automation that I wouldn't have to continuously maintain and update, so there's more work there as opposed to just hammering it out manually.

    Writing my docs manually ensures that I have full understanding of my code. I use Test::Pod and Test::Pod::Coverage to ensure all POD is in place, and beyond that, any failed unit tests will tell me that I've changed the code enough to do a review of the tests, the code (in case the change isn't what I expected) and of course the POD.

    I am not in favour really of automating documentation; to me, it's an extension of the code, so it doesn't bother me to write it.

    To further, I do periodic reviews of random distributions I have, validating the documentation is accurate through actually using the code per what the docs say.

    It sounds like you need a simple Template::Toolkit set up if what you're trying to do is auto-populate some simple documents.

[reply]
[d/l]

      I have not gotten around to Test::Pod or Test::Pod::Coverage. It's on my list.

      Right now, I'm thinking I want to strive to get the best of automation without over automating it. Personally, I find it agonizing and tedious if it's not closely related to explaining what the code actually does. I find I much prefer writing tutorials. I've played a little with TT. I'm sure someone has invaded this problem space. I'll tool around cpan some. Thanks.

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

[reply]

In Section Seekers of Perl Wisdom