How to lay out POD documentation for multi-faceted apps

[stevieb]

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

[Anonymous Monk]

Hi,

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

Also add the link in the "SEE ALSO" section

[stevieb]

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.