TechWhirl Sponsors

About TechWhirl

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.

Helping your colleagues use a standard template?

Sarah Lathrop is <<... reworking our... documentation... My
manager wants to have a consistent look and feel to all
documents created by our department... I am currently
working on a style guide. I am also creating a Word template
and sample documents that others can use.>>

I assume that someone, somewhere in the process, will review
the final documents to ensure that they conform with house
style? That being the case, your goal is really to make it as
easy as possible for your authors to use the template, thereby
minimizing the amount of rework and reformatting required
later. You could certainly create an elaborate style guide to
accomplish this goal, and maybe even program macros or
wizards to do much of the hard work, but sometimes the
simple approach is the best. To do that, create a template that
does as much of the work as possible for the users by filling
the template with all kinds of "type your name here, dummy!"
prompts that help writers do the work! For instance:

<<cover page>>

The first thing the writer would see, in large letters is the title
of the manual, but the title would be "Type the title here". The
text would already be formatted using the correct style, and as
soon as they type the title, replacing the existing text, what
they type automatically adopts the formatting specified by
that style. (Your style guide would cover for those who
inadvertently delete the "type your title here" text by defining
which style from the style gallery they should apply.) A little
lower on the page, the writer would see text that says "The
release date goes here", which is already formatted using the
"date" style. Typing the date replaces that text with the correct
date, already formatted. And so on, with comparable prompts
for each element of the page.

The basic principle, which you can use everywhere else in the
template, is to provide text already formatted in the correct
style that prompts writers with what they need to insert. As a
result, they almost never need to actually know what style to
use: they just replace the existing text. This is particularly
easy for paragraph text, since hitting the return key at the end
of a paragraph simply creates a new paragraph already
formatted using paragraph style. Bulleted lists are a little
trickier, but you can still provide a "type a bullet here or
delete this paragraph if you don't have any bullets" formatted
using bullet style.

<<standard first chapter>>

Same principle. Type each of the main headings that are
standard for that chapter, formatted using the appropriate
heading styles. If the heading names are consistent from
manual to manual, then the writer doesn't even need to retype
any text: they just use what you've already typed there. Then,
under each heading, insert the first paragraph of type as
follows: "This is the first paragraph under this heading: in it,
you need to include the purpose of the report, why that
purpose is important, and who is responsible for fulfilling that
purpose." Again, they simply type the correct text, replacing
the pre-existing text.

<<update the TOC>>

In Word, you can write a macro that activates when a
particular keystroke is typed. (In other programs, you may
need to explicitly tell users to run a macro, or you may have
to do it yourself once they submit the draft for review.) That
being the case, replace the "save document" keystroke
(control-S) with a macro that updates the TOC, and _then_
saves the file. You can add any other cleanup you want to
add to that keystroke. (I believe this was discussed a while
ago on techwr-l; check the archives!)

<<add a chapter, etc. >>

Create a template for "new chapter", following the same basic
principles I've explained (i.e., fill the file with prompts and
preformatted headings), and save it as a file. Then, create a
macro called "Add chapter" that inserts the new chapter
template at the position of the cursor. You can create
comparable macros, each with a logical and obvious name,
for any other components you need to add regularly.

<<Have any of you had any experience in getting people
outside the Documentation group to create documents
according to a standard? >>

Yes, and it never works as well as it should in theory; people
are stubborn that way. <g> The best thing you can do is to
keep it simple, provide as many tools to make it idiot-proof as
you can come up with, test those tools to make sure they're
really as simple as you think, train people how to use the
tools... and study meditation so you can gracefully accept the
fact that you and I are the only ones who will ever submit
perfectly formatted text. <g> All joking aside, the best you
can ever hope for is a reduction in the amount of work you'll
have to do. Some people will be untrainable, some won't
bother using the templates no matter how much you yell at
them, and some people will find ways to misuse the
templates. That's life!

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"Perhaps there is something deep and profound behind all those sevens, something just calling out for us to discover it. But I
suspect
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)