On Mon, Dec 9, 2019 at 12:49 Peter Scott <pe...@psdt.com> 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. -Tom
