Radical revamping of techpubs

[Ron Miller]

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: ronsmiller at ronsmiller.com
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 ronsmiller at comcast.net.
>
> Send list messages to framers at lists.frameusers.com.
>
> To unsubscribe send a blank email to
> framers-unsubscribe at lists.frameusers.com
> or visit http://lists.frameusers.com/mailman/options/framers/ 
> ronsmiller%40comcast.net
>
> Send administrative questions to listadmin at frameusers.com. Visit
> http://www.frameusers.com/ for more resources and info.