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

Re: A grand idea on the documentation

Thread Previous | Thread Next
ToddAndMargo via perl6-users
December 11, 2019 01:14
Re: A grand idea on the documentation
Message ID:
On 2019-12-10 07:31, Tom Browder wrote:
> 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.
> -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.

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