Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

How to lay out POD documentation for multi-faceted apps

by stevieb (Abbot)
on Apr 02, 2017 at 22:31 UTC ( #1186756=perlmeditation: print w/replies, xml ) Need Help??

Take Test::BrewBuild for instance.

There are three included binaries (well, scripts) that accompany the various modules that make up the distribution, but it may not be clear to a user which one to read first.

When you search CPAN for the distribution, it automatically loads the POD file for the main API module, in which I redirect users to read another doc if they are not looking to use the API directly.

What type of approaches do I have here. Should I hijack the main module's POD with the main binary's POD, and redirect to the other ones from there?

What have others done in these situations, and as an end-user, what would you like to be presented with on a first glance after clicking on a search result?

update: note that the first entry in the Changes file in the link above has been rectified, as I updated berrybrew late last week. Updating berrybrew rids one of the win10 issue. /update

  • Comment on How to lay out POD documentation for multi-faceted apps

Replies are listed 'Best First'.
Re: How to lay out POD documentation for multi-faceted apps
by Anonymous Monk on Apr 03, 2017 at 03:52 UTC


    Link the documentation overview document in the description of every app/module/doc...

    Also add the link in the "SEE ALSO" section

      Thanks anonymonk. I think I will do this. I did this in a way for another project, but not precisely.

      I like the idea of having an overview type doc, perhaps named something obvious like "README_FIRST" or the like, so that when people arrive at the page on the CPAN, it will be an obvious first choice, unless they know exactly what module/binary they are looking for. Then any FAQ/Tutorial doc stands out as well, but not before the main overview doc of docs (in the case I presented, the FAQ focuses only on specific aspects of the distribution... I should change that up with additions on all aspects of the dist as well while I'm at it).

      I appreciate the feedback.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://1186756]
Approved by Athanasius
[Corion]: choroba: I admit I've thought about it ;) But I think I'll sooner hack up the Pg parser library to spit out a good parse tree and then hack that up to create Perl code :)
[Corion]: But back when I last looked at the VM of SQLite it seemed way to basic to me to implement anything in it....

How do I use this? | Other CB clients
Other Users?
Others chilling in the Monastery: (13)
As of 2018-03-22 12:45 GMT
Find Nodes?
    Voting Booth?
    When I think of a mole I think of:

    Results (274 votes). Check out past polls.