> On Dec 9, 2019, at 10:24 AM, Curt Tilmes <[email protected]> wrote: > > On Mon, Dec 9, 2019 at 10:07 AM ToddAndMargo via perl6-users > <[email protected] <mailto:[email protected]>> 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 <[email protected]> http://www.stok.ca/~mike/ The "`Stok' disclaimers" apply.
