I would maintain, that it's impossible to facilitate knowledge
transfer without good style, form and consistency, but I would agree
that without clear writing, it hardly matters how good it looks.
You will never achieve the perfect interface. It's not going to
happen. Your grandmother is still going to be confused by what seems
inherently obvious to you. You can anticipate the needs, aptitude,
learning style and so forth of every user in the customer base. It's
simply an unreachable goal, especially in a sophisticated software
package developed by multiple developers under commercial and time
pressure. Software isn't produced in a vacuum by robots, it's
produced by humans with lots on their plates.
What we can control is that we can produce documentation that's
clear, concise, well written, well organized, and easy to navigate.
If we as tech writers aim for this goal, then I think we can at least
satisfy a good number of users, help them solve their issues or use
the software, reduce calls to customer support and help make the
product better.
The other stuff is pie in the sky to me and not likely to happen any
time soon.
Ron
Ron Miller
Freelance Technology Writing Since 1988
Contributing Editor, EContent Magazine
email: [EMAIL PROTECTED]
blog: http://byronmiller.typepad.com
web: http://www.ronsmiller.com
Winner of the 2006 and 2007 Apex Award for Publication Excellence/
Feature Writing
On Oct 18, 2007, at 11:43 AM, Technical Writer wrote:
Technical writing, specifically end-user documentation of software
applications, is perceived by the majority of producers as "less
than useful" and, in general, a waste of money, time, and effort.
Similarly, the TW's view that they are "adding value" to a product
may be just as impoverished.
Documentation is not used by the end-user because it is awkward,
poorly organized, and in many cases, indecipherable for a user
seeking task-accomplishment assistance. Linux is a primary example;
despite some of the most dedicated, motivated developers on the
planet, and droves of TWs spending endless amounts of time creating
"tutorials," introductions," and "documentation," (along with a
massive PR pitch by IBM a few years back), Linux languishes. Users
avoid it because it is "too difficult to learn."
The underlying cause begs exploration, and is at the heart of
technical documentation; does the TW really want the witless user
to understand what the TW finds conceptually difficult? Or is there
the same tendency in TW that is found in academia--"I took years to
learn this, and you expect me to tell you how to do it in half-an-
hour?"
I am not suggesting for a minute that the process is planned, or
even that the TW is aware of it. I am suggesting that the
underlying premise of technical documentation is not
"documentation" (as in "creating a record of"), but knowledge
transfer. It is in the area of knowledge transfer that TW comes up
short. Of all the software documentation available on October 18,
2007, how many pieces are considered easy-to-use by users?
What I suggest is not a simplistic condemnation of TW, or TWs. What
I suggest is that the underlying premises of TW may be
impoverished, and suffer the same weakness as academic
"instruction." That is, replaying the one-to-many lecture style of
Aristotle on the computer screen, in the mistaken belief that a
user really cares whether every i is dotted and every t crossed, or
that a consistent style is used for all code samples, and a
consistent voice is used for all explanations.
Finally, the reason that user interfaces in software applications
require extensive documentation is a failure in the design and
programming stage, not in the documentation stage. If the interface
were competently designed, it should be "intuitive" to use, and
require only minimalist documentation. If there is a future for TW,
it lies in the area of facilitating knowledge transfer, rather than
an obsession with style, form, and consistency.
_________________________________________________________________
Climb to the top of the charts! Play Star Shuffle: the word
scramble challenge with star power.
http://club.live.com/star_shuffle.aspx?
icid=starshuffle_wlmailtextlink_oct___________________________________
____________
You are currently subscribed to Framers as [EMAIL PROTECTED]
Send list messages to [EMAIL PROTECTED]
To unsubscribe send a blank email to
[EMAIL PROTECTED]
or visit http://lists.frameusers.com/mailman/options/framers/
ronsmiller%40comcast.net
Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.
_______________________________________________
You are currently subscribed to Framers as [EMAIL PROTECTED]
Send list messages to [EMAIL PROTECTED]
To unsubscribe send a blank email to
[EMAIL PROTECTED]
or visit
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com
Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.
