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