Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses

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
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (6)
As of 2017-12-16 15:35 GMT
Find Nodes?
    Voting Booth?
    What programming language do you hate the most?

    Results (455 votes). Check out past polls.