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.
Subject:Re: Giving up on XML From:Janice Gelb <janice -dot- gelb -at- sun -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Wed, 21 Mar 2007 07:38:39 +1100
Gene Kim-Eng wrote:
> ----- Original Message -----
> From: "Sean Hower" <hokumhome -at- freehomepage -dot- com>
>> I don't know if this is true. There's a difference between creating styles with the intent of using those styles to provide a
>> structure, and defining the structure itself.
> For those of us not working with an automated document structure nanny
> (to use Mike's characterization), this is what style guides are for, and we
> expect the writers reporting to us to adhere to those guides. Ever get an
> item in your upcoming review year's list of objectives that says "adhere
> to published style guide?" You have if you ever worked for me, and yes,
> it did make a difference in your end-of-year review. We are supposed
> to be professionals, and not kindergarteners who need to be lined up for
> our milk and cookies in height-ascending order, yes?
Wouldn't it be nice if the world operated like that!
I work for a company with one of the most complete
style guides in the industry and although we have
some writers who are virtuous and adhere to the
style guide, we have other writers who are convinced
that they know what's best for their readers and
ignore the style guide when it disagrees with their
view of the world. If those writers are good at what
they do, not a chance in the world that management
is going to impose enough of a penalty for them to
take their medicine and adhere to the style guide.
And we don't have enough resources on our editing
staff to play police officer and not only mark up
the document so it adheres to the style guide but
also make sure the changes are actually incorporated
We used to use FrameMaker and constantly were telling
writers that they needed to use the catalogs for
formatting and not apply bold or italic through the
menus. Guess what? When it came time to convert the
documents to SGML, some of the formatting in some
documents vanished because the writers had used the
I'd rather have structure imposed from the beginning
for the sake of consistency and clearer documentation
for our readers. Getting the writers to incorporate
editing markup of the text itself is challenge
enough. Having inescapable structure rules means
one fewer thing that will be inconsistent. Also,
some writers are better with phrasing and clear
explanations of complicated concepts and less good
at logical structure so having an imposed structure
is actually helpful to them.
I should add that we have a team that is dedicated
to making sure that our DTD serves the writers'
needs and has writer representation so the structural
rules are not imposed from above without any input
from the writing community.
Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-