> 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.
