On 2019-12-10 15:02, Laurent Rosenfeld via perl6-users wrote:
You've made a very interesting point on how difficult it is to write
proper documentation. I hope that Todd will reflect on that.
Hi Laurent,
Oh good lord. I do no have to do any reflecting
on it at all. I spend hours and hours and hours
writing directions and procedures for customers
on a weekly basis. I pull my hair out at times
trying to get things understandable at the skill
level of the user.
So, I have an extreme understanding of what it takes.
It is an art form all on its own and *it ain't easy!*
Do not take my griping about the way the docs are
presented as not appreciating the work that was
involved in getting there. Oh good lord that was
a lot of work!
One thing I do a lot is screen shots and pictures.
I love the arrow add on in GIMP. My stuff is
peppered with read arrows. That seems to work
really well with customers.
When I write for myself, I almost never use a screen shot.
I just to the
--> click this
--> click that
Long winded explanations drives me nuts. But one
has to remember their target audience and write
specifically for them. That also is also an art form!
The one thing I find about writing documentation is
that it forces me to organize my thoughts and
quite often, I teach myself thing I did not
realize I did not know.
-T
