radical revamping of techpubs

Thu Oct 18 06:53:29 PDT 2007

What makes more sense in my mind is for technical writers to expand
their role to the life-cycle of the product, from conception to
maintenance, by investing in understanding interaction design/interface
design, quality control and user advocacy positions.

--- Ron Miller <ronsmiller at comcast.net> wrote:

> 
> 
> 
> 
> On Oct 11, 2007, at 10:23 AM, Technical Writer wrote:
> 
> >
> > The trend has been in that direction since the dotcom bust, when a 
> 
> > number of (formerly) highly paid developers found a comfortable job
>  
> > writing help files more appealing than unemployment or stocking the
>  
> > shelves at Wal-Mart.
> 
> If they have writing skills, then they can make a living as a tech  
> writer, and more power to them, but just because they are technical  
> certainly doesn't mean they can write.
> 
> 
> >
> > While it is easy for technical writers to convince themselves of  
> > the value of what they do, the simple truth is that many users lack
>  
> > the linguistic and cognitive sophistication to distinguish between 
> 
> > "good" writing and "mediocre" writing.
> 
> 
> I'm sorry, but that's just a gross generalization and there's no way 
> 
> you could realistically back up the statement.
> 
> 
> 
> >
> > Similarly, it is easy for technical writers to believe they are  
> > documenting the software, when in fact they are only documenting  
> > the interface. The trend in development is to make the interface  
> > more intuitive, hence easier to use; if the interface requires  
> > extensive documentation about how to use it, it is a failure of  
> > design, not of documentation. That follows the way the overwhelming
>  
> > majority of users actually interact with software--they start it  
> > up, click a few buttons, and generally try to figure out how it  
> > works. For a well-designed user interface, that should be enough to
>  
> > get started.
> 
> Should be, but for the majority of users in the world, it's not that 
> 
> simple. My experience is that you are making a huge mistake if you  
> assume your users have the same level of computer aptitude that you  
> and your colleagues have. Of course, it all depends on audience, but 
> 
> in a typical commercial software program, I believe you have to  
> document to the lowest common denominator and that means assuming  
> little or no computer skills. If you want proof of this, look not  
> further than Office 2007 with its radical interface redesign. In  
> theory, that means it should be easier to use, but in practice, you  
> have to learn where all the tools are after years of doing it another
>  
> way. Without good training and documentation, the average user who  
> has been using Word with a menu bar/toolbar metaphor for umpteen  
> years is going to have a very rough go trying to find his/her way  
> around. Heck, I'm an experienced user and I find it maddening.
> 
> 
> >
> > The movement toward Extreme Programming and Agile Development is a 
> 
> > case in point; documentation is considered a waste of valuable  
> > developer time, and only needs to be slapped together in minimalist
>  
> > form at the last minute. That is at odds with the "TW perspective" 
> 
> > of involvement during the entire development process (which is ONLY
>  
> > appropriate for Waterfall, because everything else changes).
> >
> >
> 
> I can't speak to this because I don't delve into programming and  
> development theory, but I can say that as a tech writer with 20 years
>  
> experience, that one of my big value adds is acting as the voice of  
> the end user. Developing involves a series of choices often made in  
> haste, and often involving a number of people working separately on  
> different pieces. I've found that as a person looking at the entire  
> program, and carefully documenting how it works, I can act not only  
> as another QA piece, but also recognize inconsistencies and bad  
> choices and I can make suggestions for improving the program. If you 
> 
> bring me in at the end of the process, there is less time to react to
>  
> these types of changes. If I'm involved from the beginning, I can act
>  
> as another set of eyes.
> 
> 
> > Because there is already a dichotomy between the GUI developers and
>  
> > the "real" programmers, it is a small step to realize that the best
>  
> > people to provide the minimalist documentation necessary to use the
>  
> > interface are the developers of that interface. If the interface  
> > requires more than minimalist documentation, the core problem is  
> > the failure of the design, not a lack of technical writers.  
> > Minimalist documentation should be based on the remarks (in the  
> > code) of the developers, not a secondary understanding of a  
> > technical writer acting as a third party.
> 
> Yea, in theory, maybe, but in reality, you can't know if the GUI is  
> dead easy to use, because you can't possibly assume you know the  
> computer aptitude of your entire customer base. In my experience,  
> people have very little computer savvy and mostly know only how to  
> use the bundle of programs they use regularly. If you take them  
> outside of that comfort zone, it's like starting from scratch.
> 
> >
> > If a technical writer wants to document software, he or she should 
> 
> > learn to program competently. Similarly, a GUI developer who wants 
> 
> > to stay employed should learn the basic skill set needed to convert
>  
> > remarks in the code to help files. The dichotomy between developer 
> 
> > and writer is artificial, and not particularly useful. Developers  
> > don't need a Master's in English to write competent documentation, 
> 
> > and technical writers don't need a BS in Computer Science to  
> > develop a competent interface. When the employers realize that,  
> > technical writing--as far as software documentation is concerned-- 
> > is liable to become the 2008 equivalent of buggy whip manufacturing
>  
> > when automobiles chased the horse-drawn buggies off the road.
> > The argument that documentation would erode developer time better  
> > spent elsewhere is spurious; the process is becoming, 1) release  
> > the software with a minimalist set of docs, then, 2) build an  
> > online help file based on the highest volume of calls to support.  
> > The concept may be uncomfortable for technical writers, but it is a
>  
> > concept used widely in business; "the squeaky wheel gets the
> grease."
> 
> 
> I don't think anyone needs a Masters in English to write  
> documentation, but they do need competent writing skills, a skill  
> often lacking in programmers who have other skills. It's not  
> impossible to have a developer who can write or a writer who can  
> develop programs, but in my experience these are typically very  
> different skills sets and it's unusual for an individual to have both
>  
> sets of skills. And I would maintain that good documentation is  
> hardly the 2008 equivalent of buggy whip manufacturing. On the  
> contrary, good documentation is becoming increasingly important,  
> especially in a fast-moving global market place. The paper document  
> may be a dinosaur (maybe because I've been waiting for it got away  
> for years, and never does), but well organized and well written  
> online documents can actually reduce those calls to support before  
> they happen, and a good analytics tool can be used to find gaps in  
> that documentation, not replace it.
> 
> 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
> 
> 
> 
> _______________________________________________
> 
> 
> You are currently subscribed to Framers as athloi at yahoo.com.
> 
> 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/athloi%40yahoo.com
> 
> Send administrative questions to listadmin at frameusers.com. Visit
> http://www.frameusers.com/ for more resources and info.
> 

http://technical-writing.dionysius.com/
technical writing | consulting | development

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 