On 2019-12-10 07:31, Tom Browder wrote:
On Mon, Dec 9, 2019 at 12:49 Peter Scott <pe...@psdt.com
<mailto: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
I like the idea. I also like it being centralized.
And Todd or whoever chose to write in it would get a lot
of great peer reviewing that would vastly help his/their
technical writing and programming skills. And help
others too.
