develooper Front page | perl.perl6.users | Postings from December 2019

Re: A grand idea on the documentation

Thread Previous | Thread Next
Tom Browder
December 10, 2019 15:31
Re: A grand idea on the documentation
Message ID:
On Mon, Dec 9, 2019 at 12:49 Peter Scott <> wrote:

Developers need reminders, in the most succinct form, to minimize time,
> of data that they should not need to memorize.  The documentation
> satisfies that need in the same way that a phone book satisfies the need
> to look up someone's number.  The phone book is not bloated with
> explanations of each person's favorite food or the history of the phone
> company.
> Your 'keeper' documents sound like they should be shared with others who
> may be in the same situation as you.  Please follow the suggestions for
> how to do that so you can see how they are received.

I have a suggestion that might be a solution, and I tried to get interest
in it in 2015 or 16 when the docs were starting to get a lot of attention:

+ Start something like a Cookbook similar to the printed one published by
O'Reilly for Perl (but watch out for copyright issues such as identical
sections and layout)

Put the cookbook on the current docs site. The docs could stay the way they
are, but, as suggested above, have links into the cookbook for recipes for
real use cases like Todd wants.

With the tooling in place, Todd could start adding his stuff in the
appropriate place, and it would be fair game for editing as necessary.

Also as suggested above, the layout and links to and from the (reference)
docs and the example docs could be automated.


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About