On 17 Jul 2005 03:11:56 -0700, "sam1967" <footballdvds@gmail.com>
wrote:
>Some manual's tend to be too techy and should include a
>simplified How-To or Walk Thru such as the above.
Once upon a time, I used to write the manuals for the hardware I
designed. Through trial and error, I learned that there was no
possible way to write a single manual that satisfied every possible
user and customer. The geeks wanted techy detail. The users wanted
plug and play. The lawyers wanted massive disclaimers. Shipping
wanted a packing list. Sales wanted it to sell accessories.
Marketing wanted it to be an applications guide. Support wanted it to
reduce the support load by including lots of troubleshooting advice.
QA wanted to a few pages of certifications. The military wanted it
readable by a high skool dropout. The desktop publishers thought that
huge margins all around made it more readable and was more than happy
to remove content to add additional margin space. I don't know who
threw in the "read me first" page. If an elephant is a horse designed
by a committee, some of my manuals were elephantine in size. Nobody
was happy with the results.
What I found hilarious was at the time (late 1970's through 1980's)
the form and style of consumer electronics product manuals were being
established. There was no formal organization in charge or
orchestrating the effort. What was happening was that every company
was copying the style stolen from some other company, on the
assumption that the other company knew what it was doing. Nobody was
happy with their documentation and the competition always seemed to
have a better idea. I could honestly say that documentation style was
established with a Ouigi Board.
>Plus it also shows why a teacher is invaluable as someone who has spent
>months/years reading the manuals and implementing the stuff is in a
>great position to offer concise instructions to a beginner .
Agreed. Experience is the best teacher. That's why my domain is
"LearnByDestroying.com". You don't really understand anything until
you've destroyed it and had to resurrect and fix it. Lack of
experience is also why support people cannot offer much in the way of
assistance. They haven't gotten their hands dirty and therefore have
only someone else's experience to follow.
I have a simple style for setting up complex devices. It's similar to
your step by step procedure with *LOTS* of examples. In my never
humble opinion, people learn from examples, not from explanations.
Therefore working examples are required. I also separate the "do
this" from the explanation why they are doing this. Many people do
not want to be bothered knowing why you need a WE128 key of exactly 26
hex digits. Tell them to type in 26 hex digits, and promise them it
will work. They'll do the rest.
I don't have any relevant examples of how to write a setup and install
procedure online. The closest approximation is the Windoze 95/98/ME
setup instructions for MRTG software at:
http://www.LearnByDestroying.com/mrtg/docs/w95mrtg.htm
It's 5 years old, gone through a few revisions, and works every time
if followed in the order shown. Wireless router manuals could be
written in a similar style, but rarely are.
>Just ask Jeff.
I needed the rant...
--
Jeff Liebermann
jeffl@comix.santa-cruz.ca.us
150 Felker St #D
http://www.LearnByDestroying.com
Santa Cruz CA 95060 AE6KS 831-336-2558
Wireless networking quandry (noob question) 
Linear Mode
