Document layout: Whose decision?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Nicole wonders: <<To what extent is it your decision as the tech writer/tech
writing department how to lay out manuals,
and to what extent is it the programmers' decision?>>

I've worked in several different situations, ranging from no programmer
input whatsoever (or "author input" in most cases, since program docs form a
relatively small--though growing--part of my job) to a fully collaborative
process, with give and take on both sides. In each case, the graphic artist
or desktop publisher and I have had more weight in deciding such things
since we have more expertise in this field. However, where the
author/programmer/whatever is representative of the audience we're trying to
reach with a particular publication, we're always careful to make sure we
really know the audience better before we insist on doing it our way. Over
the years, I've developed a pretty good BS filter for recognizing when an
author really knows the story and when it's just a matter of personal
preference. I've also learned some valuable things when it turned out I
didn't know the audience as well as I thought.

<<Our department set up a style guide and set of manuals... All docs have
been done that way since we set it up last July... A programmer who usually
does not need documentation recently needed a doc done and complained that
he wants it without the side-head - in other words, he wants the lines to go
all the way across. (He didn't say why.)>>

The lack of a good reason tends to trigger my BS filter. If he can't provide
a reasonable explanation for why his approach is better than the one that
everyone's accepted for the past half year, you shouldn't feel obliged to
accomodate his request. However, not everyone can explain why something
doesn't work even when they know that's the case. And don't forget that the
mark of a good designer is knowing when to break the rules: sometimes a
template that works just fine for 95% of your work fails to meet the unique
needs of the remaining 5%. (We find that to be the case here with the
technical reports we publish, even though we designed the templates with
flexibility in mind.)

<<I also don't relish the idea of comping up with another template. It would
not be terribly hard, but especially for this document (it has tons of
special formatting and weird tables and other odd things) it would be a real
pain.>>

The phrase "tons of special formatting and weird tables and other odd
things" is a strong clue that the document has unique content or needs that
will require you to adopt a slightly different approach. There's no way for
me to tell whether this is true in your case, but you should certainly try
to consider the request for a different design objectively. As I noted
earlier, the fact that the programmer can't use techwhirler jargon to
explain the problem doesn't mean that there's no problem. Maybe the
programmer has a good point this time, and maybe you can come up with a
compromise that preserves most of the consistency with other manuals while
still accommodating the needs of this one. And maybe the guy's just being a
jerk--but you're the only one who can tell us that, provided you consider
the situation fairly.

<<My feeling is that, I don't tell them how to program; they don't tell me
how to lay out documents.>>

Though this attitude is reasonable, it can also create a bad relationship
between you and the programmers. I would hope that you have the right to
tell them when the interface sucks (and why and what to do about it) and
have your opinions taken seriously, and that implies that they have the same
right concerning your documentation. The key here is to discuss things, and
only if you can't find a way to accomodate each other should you consider
digging in your heels. Sure, you win the battle, but maybe in the long run
you'll end up losing the war.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The problem with defending the purity of the English language is that
English is about as pure as a cribhouse whore. We don't just borrow words;
on occasion, English has pursued other languages down alleyways to beat them
unconscious and rifle their pockets for new vocabulary."-- James D. Nicoll

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by ForeFront, Inc., maker of ForeHelp Help authoring tools
for print, WinHelp, HTML Help, JavaHelp, and cross-platform InterHelp
See www.forehelp.com for more information and free evaluation downloads

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.