Helping your colleagues use a standard template?

["Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca>]

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)