Re: Documenting field descriptions in printed documentation

Subject: Re: Documenting field descriptions in printed documentation
From: Tom Murrell <trmurrell -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 18 Sep 2002 08:19:06 -0700 (PDT)

--- kcronin -at- daleen -dot- com wrote:

> Tom, I'm all about teamwork. Part of teamwork is each member doing what
> they're supposed to do. IMO, if EVERYTHING is a group decision, efficiency
> suffers, bigtime. Think about it: When a deadline is announced, do you
> launch a "team-building exercise" so that everybody can "share their
> feelings" about the deadline? Or do you say "It's due in two weeks - we
> better get a move on"? Most businesses are not democracies - we have
> bosses who tell us what to do. I'm suggesting that you appoint a Style
> Boss. You want democracy? Then VOTE on who that person will be.

I fully agree that when you have to meet the deadline, everbody on the
team needs to be focused on that. I tend to think that style issues
are not handled on the critical path. Ideally, they are handled before
projects are that far along. In those areas where I've worked with a team,
either the Style Guide already existed or style questions were addressed
before the project got so far along that rework was created. If you just
fire a team of writers out into a project with no idea of how you will
regulate style questions, you have a recipe for disaster. Certainly, it's
disaster if you stop a project as deadline approaches to resolve issues of
style that should have been resolved early on. I think your argument creates
a mess of a situation that 'requires' that issues be resolved quickly that
should have been resolved early on.

> If the style guru has the necessary support (ie, cooperation and
> compliance), there should BE no sniping. There should be shutting up and
> writing.

Granted, but I don't know what world that is where dictated decisions are
not second-guessed, griped about, and even subverted. (Unless you're an
intimidating presence, as I am, and people naturally bow to your superior
wisdom. <g>) Again, and I can't stress this enough, we're talking about two
different things. I think you develop your style guide (or answer style issues)
either before the project starts or early in the project, before you are in
a deadline crunch. The idea is to avoid rework at the last minute caused by
people wandering off and doing their own thing. And I think you develop your
style guide by consensus. If no consensus can be reached, well that's what
managers or lead writers are for: to make the tough decisions.

> I'm down with the last half of that statement: "...everyone agrees to
> follow." But my experience in trying to get a group consensus on each
> piddly little style decision is that it takes FOREVER, and that there will
> always be somebody who's discontented with the results, no matter how
> democratically they were achieved.

Yes, it does take longer to achieve a consensus. That doesn't mean you
shouldn't try, when you have the time to do so. I'm simply thinking that if
we try to work together, we'll accomplish more than if we have to do something
"because the boss says so." Being the boss is a lot easier (on the boss) than
building a team. Being expedient in the short term may seem the simplest
approach. I guess I like to consider the longer term implications and establish
a more collegial working relationship, where possible.

> Maybe my glibly mentioned "style nazi" term spawned this "tyranny" take on
> this. But I assume you have a boss. Does the fact that you have to do what
> he or she tells you mean that you're living under a tyrant? Or simply that
> somebody has been given decision-making authority? I agree, a good team
> SHOULD work together toward a common goal. But most good teams have
> leaders, to help keep them focused on that goal. Strong leaders are not
> necessarily tyrants.

Yeah, I have a boss. He's pretty good at doing what I tell him. <g> Seriously,
generally speaking I work best with bosses who tell me WHAT they want and when
they want it, and then get out of the way while I figure out the HOW of it.
When there is a problem with the what or how, we work it out together, because
the boss knows two things about me: if he works with me, he'll get what he
wants, and if he doesn't work with me, he won't like the results. (Besides, I
remind them all that I was looking for a job when I found this one.)

So, if there's a tyrant in this equation, it's probably ME. <g>

> I've worked in both scenarios: a team deciding on their styles through
> discussion and debate, and a team selecting a Designated Driver for their
> style decisions. I much prefer the latter. Your mileage obviously varies.
> But have you tried both approaches?

Yes, I have worked in both scenarios, and I've successfully delivered what was
needed in both scenarios. I can work with people, and I can work independently.
Frankly, I prefer to work pretty much independently; it cuts down on staff
meetings. <g> But I can work effectively with others. I can even let them have
their way when they are obviously wrong about a style issue. <g> And, you know,
it's a funny thing about working with other people; if you don't have to win
every argument, you can win the important ones.

Most of the stuff we discuss on this list revolving around questions of style,
is not worth arguing about. One space or two? Who cares? Serif or sanserif? Again,
who cares? Pick one and move on. How you layout descriptive information for the
user? <whispering> It doesn't matter.</whispering> Just lay it out consistently.
The user/reader will figure it out. Look at the documentation that does exist.
Most documents are done differently than either you or I do them, and when they
don't work, it has less to do with layout than it does with content. So, in my
book, it's trivia, and I try not to waste too much time on trivia.

Something else to consider: we don't have to allow ourselves to be dragged into
every style question that is posted. Most of the time, the posters are in an
argument at work, and they want US to side with THEM so they can WIN. So, I
mostly don't get involved in those Holy War threads because it really doesn't
matter what layout you use or what font or what software. Now you know just
what sort of heretic I am. <g>

I do think that working together for the common good is worthwhile and makes for
better working relationships and better products that dictating and giving
orders. If you think ahead (a rare commodity, I realize), you can prevent
coming to deadline time and find that five writers have chosen seven different
ways to layout the same type of text, and now there's no time to make it look
like it came from the same place.

As the man said, "Plan ahead. You might need one."

Tom Murrell
mailto:tmurrell -at- columbus -dot- rr -dot- com Last Updated 08/30/02
--When asked what he thought of Western Civilization, Mahatma Ghandi is reported to have answered, "I think it would be a good idea." (

Do you Yahoo!?
Yahoo! News - Today's headlines

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever!

FrameMaker-to-PDF TimeSavers Assistants let you enhance & automate navigation
in PDF doc sets (chapter tabs, next/prev chapter/pg, bookmarks, popup menus);
create interactive PDF forms, rollover popups; presentations:

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 for more resources and info.

Previous by Author: Re: Documenting field descriptions in printed documentation
Next by Author: RE: Funny Tech Writing
Previous by Thread: RE: Documenting field descriptions in printed documentation
Next by Thread: Re: Documenting field descriptions in printed documentation

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

Sponsored Ads