Radical revamping of techpubs

[Rene Stephenson]

Lots to digest here:

Technical Writer <tekwrytr at hotmail.com> 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. 
  This is observable.
  Similarly, the TW's view that they are "adding value" to a product may be just as impoverished. 
   I certainly hope not. If it is, TW's are forgetting some key  ingredients of good writing:  relevance, usability, and  accessibility. (By accessibility in this instance I don't mean as  relating to accomodating certain challenges the user may have; I mean  the ability of the user to actually FIND the information they seek,  assuming that the information is there.
  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.
   People who aren't avid readers in general don't turn to books for  answers, but an increasing number of users do try to find answers  online, either via the F1 key or an internet access point. The whole  reason I got into TW in the first place is that I was extremely  frustrated as a user of the books for the programs necessary for my job  at the time. I was marking up the books with "no, it really works like  x" and catching typos and grammar errors. Now that I've spent over a  decade in TW, I can honestly say that a lot of the reason for the  user's frustration is probably rooted in the excruciatingly short  timelines required of most TWs, as well as the all-too-common  presumption by the TW and/or their management that an review by a  qualified editor is a "luxury."  There are many contributing  factors. 
    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? 
   Document usability and readability enable or incumber knowledge  transfer at least as much as relevance and organization of the content  do. However, of the scores of TWs that I've worked with over the years,  several with at least 25 years in the field, many are completely  unfamiliar with basic concepts of how to make clear, concise  information that is easy to find and easy to read and actually relevant  to the user. It's been my experience that only about 1/4 of the TWs  I've met "get" those concepts. Most of them are really good at  understanding their subject matter and getting the point across to the  reader, but many get too many tangiential factors involved or fail to  understand how the user approaches the product and, therefore, fail to  organize the information in a way that the user needs it presented,  much less index it with terms the user would seek. There are a few  companies that are customer-focused enough to get the TW's efforts into  some doc
 usability scenarios, but these companies seem more the  exception than the rule...at least in telecom.
  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. 
    In telecom, even the most intuitive user interfaces require  documentation to explain the system ramifications and configuration  options available with various combinations of settings. Some of it  could be converted to field-level on screen "what's this" roll-over  text, but a lot of it requires interrelational understanding as applied  to various scenarios and goals. No screen, regardless of how  intuitively it is designed, can convey that information...to the best  of my understanding or estimation.
  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.
   Yes, the future of TW does rest *partly* in facilitating knowledge  transfer. It also includes knowledge management and creating and  maintaining a bridge between what the customer does with the products  and what the company provides as products for the customer.
  
  My 2¢
  Rene Stephenson