On Sat, 10 Aug 2013 07:14:43 -0700 (PDT)
"Edward K. Ream" <[email protected]> wrote:
> Documentation has several purposes:
>
> 1. Most importantly, to announce that a particular feature exists.
> People have no way of trying feature otherwise.
> 2. To provide the *minimum* need for people to start using a feature.
> 3. Least importantly, to provide all the details.
4. Cut down on tech support calls.
5. Limit user frustration.
6. Give your program a better reputation (because of 4 and 5)
Most man pages I've seen are useless as anything but reminders because
they violate rule 2 above.
>
> It's easy to overlook these priorities. Often, we seem to get them
> backwards by jumping in with the details before explaining what a
> feature does! I'll attempt to keep them in mind as I revise the
> release notes.
My wife was a preschool teacher before our triplets were born, and she
taught me two things I still use when standing up before technologist
and giving them a 16 hour Universal Troubleshooting Process course:
A. From the familiar to the unknown
B. Do the following:
1. Tell them what you're going to tell them.
2. Tell them
3. Tell them what you told them.
SteveT
Steve Litt * http://www.troubleshooters.com/
Troubleshooting Training * Human Performance
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/groups/opt_out.
