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
