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: [EMAIL PROTECTED]
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 [EMAIL PROTECTED]
Send list messages to [EMAIL PROTECTED]
To unsubscribe send a blank email to
[EMAIL PROTECTED]
or visit
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com
Send administrative questions to [EMAIL PROTECTED] Visit
http://www.frameusers.com/ for more resources and info.
