Re: Software solution (tech writing tie in)

[Arlen -dot- P -dot- Walker -at- jci -dot- com]

Chris is right, there is an important TW tie-in over this. But it may not
be what he thinks. Because he starts out with an incorrect premise.

>I think there is actually a technical writing point here. Unix is a system
>designed with the expert user in mind.

The fallacy is the assumption that Unix was ever designed. It just grew.
Things were added to it as someone thought of them. As a result, it's a
disorganized hodge-podge of useful little thingies. Some commands will
respond to "--help" some merely to "-h" and still others want "-H" or "-?"
or merely "?" before they'll tell you a little about themselves. Others
will do so if you simply type the command name alone. Any resemblance of
one parameter list to another is strictly coincidental (as is any
correlation between the command name and its function). Rube Goldberg is
the prototypical Unix software guy.

Segue to writing: In the early days of Macinotsh, there was The Book. It
was The Macintosh Bible, and it was good. You could find nearly anything
you wanted to know about a Macintosh in it. But as it passed through
edition after edition its strength became its weakness, as the tidbit of
information you wanted was lost in the disorganized heap of facts it had
become.

We've all got projects like that. A doc set that's been around longer than
dirt (perhaps it even contains the original specification for dirt). And
over the years we (and other writers who have worked on it) have added this
appendix, that feature list, those user procedures, and in general slapped
a new coat of paint over its rusting hulk and sent it out on the road
again.

But it's lost the organization that made it useful Back Then. It needs to
be redone. We need to avoid the pit Chris fell into, that of conflating
complexity and power. Complexity is *not* related to power; it's directly
related to the ability and ambition of the designer. Complexity is an
accidental by-product that can be controlled; simplicity only happens on
purpose. Real power is in simplicity, but that's hard to achieve, and
because it's hard, many designers give up the attempt, while still others
attempt and fail.

That Doc Set From Hell I mentioned earlier? That's complexity. It's our
sworn enemy. It's crept in over the years, aided and abetted by our
laziness and that of those who came before us. Simplicity is our ally. In a
nutshell, what we do is take complexity and make it simple, so our readers
can do what they need to do. In all our discussions of tools and pre-fab
technique, we sometimes lose track of that.

Have fun,
Arlen
Chief Managing Director In Charge, Department of Redundancy Department
DNRC 224

Arlen -dot- P -dot- Walker -at- JCI -dot- Com
----------------------------------------------
In God we trust; all others must provide data.
----------------------------------------------
Opinions expressed are mine and mine alone.
If JCI had an opinion on this, they'd hire someone else to deliver it.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.