Re: apologia pro vita sua (was Re: The Old Argument: FrameMa

Subject: Re: apologia pro vita sua (was Re: The Old Argument: FrameMa
From: Harry Hager <hhager -at- dttus -dot- com>
To: techwr-l -at- lists -dot- raycomm -dot- com, mbaker -at- omnimark -dot- com
Date: 24 Jan 2000 10:51:16 -0600


Please don't take offense with any of this but for one that is so
dogmatic in your statements about the skills needed or not needed by a
technical writer, it would help us if we knew a little about the kind
of software you support with your technical writing skills:

1. Do you document Windows-based software? That is, does the software
you document run under any of the Windows or Windows-type operating
systems (including Macs) and fully use the GUI elements of windows,
menus, dialog boxes, list boxes, command buttons, and so forth? My
guess is that the vast majority of the LISTERS reading this, document
this type of software.

2. If the answer to question 1 is yes, do you include screen shots of
any of these GUI elements in your documentation? If you do include
screen shots of any GUI elements in your documentation, are you
telling us that you don't need to be concerned about page layout and
so forth, and that you let a graphic artist or DTP person handle all
these issues?

3. Do you instead document command line interface software? My guess
is that only a relatively few LISTERS reading this, document this type
of software today.

4. If the answer to question 3 is yes, perhaps the whole issue of
graphics, page design, and page layout is relatively unimportant to
you. If this is your world, I understand why you might think that
these skills are not important technical writing skills. However, to
take generalizations about the skills needed or not needed by a
technical writer in the world of command line interface software
documentation and try to apply them to a technical writer in the world
of GUI software documentation is perhaps erroneous, at least in so far
as the skills related to graphics, page layout, page design, and other
DTP skills.

H. Jim Hager
Deloitte Consulting
Pittsburgh Solution Center

______________________________ Reply Separator _________________________________
Subject: apologia pro vita sua (was Re: The Old Argument: FrameMaker
Author: mbaker -at- omnimark -dot- com at Internet-USA
Date: 1/22/00 11:31 AM

To all those generalists who were offended by my comment that if people
asked to do too many things they will not be able to do them all well, my

There is certainly a role for the generalist. Small companies who can't
afford a team, and who have fairly simple technology, can doubtless benefit
from a technical communication generalist.

However, it is still true that you can't do 6 different things, especially
complex and important things, as well as you can do 1 or 2 things. If you
are convinced that you have mastered 6 or 7 different professions then you
are either DaVinci, deluded, or you have mastered 6 or 7 things of no
If you have hard technology and big writing challenges, you need specialized
writers supported by a team of professionals in different disciplines.

If I need a plantar wart removed from my toe, I go to my family doctor. If I
need triple bypass surgery, I go to a surgeon who will work with a team of
highly skilled and highly specialized professionals.

The more difficult the task, the more you need to specialize and the more
you need to work with a team of other specialists from different

To those who seemed to think that I was dismissing the importance of design
and layout, nothing could be further from the truth. My first tech-writing
job, before I know there was such a profession, was a procedures manual for
a desktop publishing shop. I know that page design and layout are hard
skills that take a lot of time and energy to do well. A generalist can learn
the basics. But a dedicated expert has more to offer.

I think most people here would scream blue murder if a graphic designer came
on this list and said they do a little technical writing on the side to
improve their employability. It's not that easy, we would tell them. And we
would be right.

To those who suggested that they needed to keep control of layout because
layout affects comprehension I have two things to say:

1. In so far as this is true, it strengthens the argument for having a
professional do your design and layout since they better understand these
impacts. One of the hallmarks of a poor writer is that they write things in
a way that best summarizes their existing knowledge for themselves, rather
than considering how their words will impact those who do not already know
and understand. A good writer who is a poor document designer will likely
make exactly the same mistake in design and layout.

2. It should not be true. Your content should be comprehensible independent
of presentation. Presentation should aid in the ergonomics of reading, but
it should not impact meaning or comprehension. To the extent that it does,
it is bad design. To the extent that text is susceptible to having its
meaning altered by presentation, it is bad text. (There are exceptions, but
they are rare.)

With the continuing growth of information reuse and single sourcing, the
importance of producing content that is independent of the eventual means of
presentation is vital. More and more, content creators will be removed both
in time and space form the design and the presentation of information
products that use their content.

Finally, to those who think I am being unrealistic about the job market, I
know most companies require writers to do DTP. My point is that in most
cases they shouldn't. Wherever possible, they should build a
multidisciplinary team of writers, editors, designers, programmers, and
production people. Where everyone gets to practice their specialty at a high
level, you will get higher quality and higher productivity. Single sourcing
is going to require us to adopt this model anyway, but it should be the
normal model for all departments of a reasonable size.

As to future job prospects, I think the economic inefficiency of the current
model is becoming more and more apparent to many companies. To a lesser
extent, perhaps, the quality impacts are being noticed as well. I expect to
see things changing soon.

When it ceases to be the normal expectation of a technical writer that they
do page design, layout, and pre-production, the quality of technical
communication will improve markedly. There was a time when the barber pulled
teeth. Perhaps in some isolated communities, they still do. I want a
professional dentist.

Mark Baker
Senior Technical Communicator
OmniMark Technologies Corporation
1400 Blair Place
Ottawa, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com

Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at or mailto:training -at- weisner -dot- com -dot-

Sponsored by Rose Hill, Your Business and Career Coach.
"Assume Success! Live Your Passion!" Get the gist at then call 503.629.4804 for details!

You are currently subscribed to techwr-l as: hhager -at- dttus -dot- com
To unsubscribe send a blank email to leave-techwr-l-27056L -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: Re[2]: The Old Argument: FrameMaker vs. MS Word
Next by Author: Re[2]: apologia pro vita sua (was Re: The Old Argument: Fram
Previous by Thread: Re: PDF's Last Gasp and Chaos
Next by Thread: Re: apologia pro vita sua (was Re: The Old Argument: FrameMa

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads