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.
> In my opinion it is not your place to be giving ANY "suggestions" unless they
> are requested.
> You're a technical writer, not an engineer, correct? Your job is to write
> documentation about what engineers design. It is not your job to design the UI.
> That is the engineer's job.
Normally, Andrew, you're mostly in the right forest, but this time you took the
wrong path. Waiting till asked is one strategy for getting useful information, or
for making a usability contribution to the overall software/hardware product, but
it's a passive solution and sometimes a technical writer is expected to make more
> Give the engineer what she asks for and let her chart her own course. If she
> designs a crappy UI - so be it. It is arrogant presumption to assume you can
> design an interface better than her. How will she learn if you butt in and
> tell her how to do her job? If you don't allow people to make mistakes they
> will never learn anything.
If that were true all the time, we'd have generations of kids who never made it to
adulthood because their parents didn't stop them from playing in traffic.
These days technical writers - and especially highly paid consultants - are more
often expected to be part of a product team and to contribute their perspectives on
overall product design. More and more these days that includes user interface.
However there's a difference between barging in on an engineer and starting a
conversation by pointing out everything that's wrong with an interface, and making
more subtle, perhaps even manipulative, comments that let the engineer know that a
writer knows something about interfaces too. In other words, sometimes it's up to
the writer to create a conversational atmosphere where the engineer recognizes that
there's value in the contributions of a writer in this particular area.
> Moreover, you cannot criticize people's work until you earn their respect. You
> have to let them screw up first and then, when asked, help them to do better.
Most programmers, when asked to do a user interface, have already demonstrated to
themselves - and usually others - that they can't do everything perfectly and are
willing to ask for help. Some even ask for help before they begin - like asking
for marketing specifications or whatever passes for other people's ideas about what
ought to be there. Waiting till someone recognizes that they've screwed up can
take a long, long time and usually does a disservice to the rest of the team. As I
said before, there are subtle ways of offering your help.
> In my line of work, consulting, butting in on an engineer's work would be a
> easy way to get term'ed off a contract. If I was not hired to design a UI, then
> I am not going to act like I am. If the client wants to design a bad UI, they
> have that right. Likewise, if an engineer wants to build a crappy program, let
> them. Let their incompetence shine, then people will be begging for your help.
And in my line of work, consulting, I find that our clients are much more
appreciative if we tactfully make suggestions along the way, even if we weren't
strictly hired to create a user interface. Let me give you one example: I happen
to hate bare-bones command line prompts because most new users haven't a clue what
to do; it takes learning about the system, one way or another, for them to realize
that they can enter commands at the equivalent of a C:> prompt and not do something
like wipe out buffers or cause other serious problems. A lot of engineers, working
so close to the hardware and the assembly code they sometimes have to use, don't
even realize that their users are going to be so flustered at first, so when they
show their command line interface to me the first time, it makes sense for me to
show my impromptu reactions like scratching my head, not knowing what to type,
etc. In so doing, I'm being a user advocate - representing the interests of the
protypical user - and I'm making a contribution to the user interface. Whether
this causes them to go back to their keyboards and create something friendlier is
not something I can control, but my reactions have already made a contribution, if
the engineer is even halfway sensible. What I've often found happens next is that
said engineer is likely to continue to use me or someone like me as the designated
"naive user" to test out assumptions about what works and what doesn't.
Have I butted in? Not at all. Have I made a subtle but probably important
> II do not feel technical communication has anything
> to do with being a "advocate" for the user. This is something a lot of tech
> writers use to distract themselves from their primary task - production of
The problem with this perspective is that it assumes "documentation" is the type of
product that works best at what the technical writer's real mission is: to get a
user from a state of not knowing into a state of knowing. "Documentation" usually
means printed material or its corollary online. That definition has little to do
with understanding the many ways people learn, and how technical writers can make a
contribution across that spectrum. It also assumes that all people learn how to
use a product strictly from reading. And most of us can give you chapter and verse,
Andrew, on why THAT isn't true.
> Technical writing is information delivery, or as I like to say, "ramming as
> much information down the user's throat as painlessly as possibly." Deliver
> good information and let the user find his/her own way.
Delivery of good information involves not just the message, but the medium as well.
It also involves understanding the users of the product, and the different ways
they approach learning. A spiffy screen arrangement is useless to a blind person;
use of one industry's jargon is meaningless to a person who doesn't know said
jargon; 10 years ago very few users understood what it meant to "close the window"
on a computer screen and even now a lot of people get confused when you tell them
to "click the close box" when there isn't a button or box labelled "Close" on the