TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Although Hedley sent this to me via private email, there are some good points
here worth expanding upon:
--- "Hedley Finger (EPA)" <Hedley -dot- Finger -at- ericsson -dot- com -dot- au> wrote:
> So, when your client's style guide violates every principle of information
> design and human psychology, it is your DUTY as a professional to point it
> out. What would you think of a doctor that came and applied a plaster to
> your boil but failed to tell you that it was an allergic reaction to the
> alpaca shirt you were wearing?
No, sometimes it is NOT your duty to point out the faults. Tech writing is NOT
synonymous with medicine. There are times when you have to accept the
environment as is and make do. Especially as a contractor.
Many companies don't care about human psychology and the theory of color. They
want docs fast and cheap. They don't need a lecture in the latest productivity
fad and how the Rational Master Blaster Methodology will make them more
You have to realize that just because a book (teacher, pontificating A-hole, or
Techwr-l member) says "this will make you more productive" does not mean it you
should implement it. Sometimes the best solution is to just jam out the docs
and streamline the process later.
> But you cannot simply high-handedly go ahead and implement change. Point
> out that the client's document comes a poor last to that of the competitor.
> Demonstrate the inadequacy or lack of informative running heads, Make a
business case: my
> recommendations save $$$$/year in time not lost in trying to locate
> information. My recommendations will save $$$$/year because FrameMaker
> conditional docs enable many different product versions to be documented in
> a single file set. Point out the drabness of the cover and layout compared
> to the gorgeousness of the Web site and the GUI. Show that restructuring
> the document will improve maintainability and reader accessibility. Show
> that adding 2 points of leading actually improves readability.
This may be fine for tech writers who work in industries with 97 year
production cycles. But back here in the third dimension - production cycles are
fast - especially in high tech. There isn't time to waste on showing the
universe the exquisite wondrousness of leading or single-sourcing.
Once again - I know it FEELS right to make business cases and show how
FrameMaker is more valuable, etc. But this is still one-off from what you
should be doing - writing the damn documents.
FrameMaker is a perfect example of how tech writers have ramrodded many
companies into using tool that is way in excess of what they need. Just because
it can do this, that and the other thing does not mean you NEED to any of that!
In the fast paced world of high tech it is often preferable to do it quick and
get it over with because the whole frickin' universe will change tomorrow
Yes, I know it seems very logical and proper to set up single sourced documents
and develop effective styles. And I know it may seem like in the long haul,
these things will save time. However, you don't always have a long haul.
Today's high-tech world changes very fast. Therefore, the real benefit today is
not saving time 12 months from now. It is the ability to tear everything down
and replace it at a moment's notice.
> You get the idea ... . As with most issues, it depends. So, can we all
> agree that presentation, structure, accessibility, and expression all
> contribute to information transfer. And whenever, in our opinion as a
> professional communicator, one of these factors is not doing the job, isn't
> it our professional responsibility to make a reasoned case for improvement
> to the client?
Not always. Sometimes it is best just to shut up, pound out a document and go
home. "Improvement" is not always real improvement. Sometimes the best
solution is the least complex. I know that may feel wrong and counter to what
we all learned at "be a good little worker school". But we don't live in a
world of endless time and money. At some point you have to stop jerking around
conjecturing over all the great ways something COULD be done and just sit your
ass down and write the damn document.
This all rolls back to a very basic business principle: results speak louder
than ideas. To make money you must produce results. Ideas and theories are
worthless unless you can put them in motion and get results.
Do You Yahoo!?
Talk to your friends online with Yahoo! Messenger. http://im.yahoo.com