That looks like a great recommendation.
On 12/9/19, Mike Stok <m...@stok.ca> wrote: > >> On Dec 9, 2019, at 10:24 AM, Curt Tilmes <c...@tilmes.org> wrote: >> >> On Mon, Dec 9, 2019 at 10:07 AM ToddAndMargo via perl6-users >> <perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote: >> On 2019-12-09 02:00, JJ Merelo wrote: >> > Other than that, it's clear from the context that it returns a Boolean >> You still need to change the target audience of the docs >> from the Developers to the Rakoons. >> >> The reference documentation (especially deep inside) is NOT intended for >> brand new people to the language. >> >> They need to start with the introduction, the tutorials, the books, even >> classes (many are available for free on youtube). >> >> The reference documentation is for someone already somewhat familiar with >> the language, but can't remember the exact calling sequence, or order of >> arguments, or exactly what gets returned, etc. The MOST important piece >> of documentation needed is the precise signature that concisely presents >> that information. That is much more important the accompanying verbiage. >> >> If one hasn't yet learned what "()" ":D" or "-->" mean, I would kindly >> suggest that they should review the introductory documentation or some >> tutorials prior to delving into the detailed technical reference >> documentation. >> >> Curt >> > > > I have found that https://www.divio.com/blog/documentation/ > <https://www.divio.com/blog/documentation/> helped me understand more about > why I have had problems writing documentation. > > Mike > > -- > > Mike Stok <m...@stok.ca> > http://www.stok.ca/~mike/ > > The "`Stok' disclaimers" apply. > > > > > > >
