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.
> I have the chance to revise our company's internal and external document
> templates. I plan to:
> 1) Ditch the chaotic mess of styles that have accreted and restore
> the original built-in versions of Word's list and heading styles
Heading styles, yes definitely use the built-in styles and by all means use
automatic numbering for them.
For list styles, it has been my experience that using the built-in list
styles seems to suffer from the "Jason tabs" problem when I modify the
indentation of the style (extra unwanted tabs keep coming back no matter how
many times I try to kill them!) Therefore, I'd recommend setting up a
separate set of list styles. I've never had Jason tabs appar in custom
styles with list numebring attached.
If you can to this in VBA without touching the list galleries (the Format
Bullets and Numbering dialog), then the styles will be much more stable.
I would also recommend you make the styles as easy as possible for people to
use by putting them on a toolbar. This article shows you how
> 2) Redo the heading styles to meet our needs (i.e. hijacking
> Heading 6 through Heading 9 for appendix headers)
Very good. Do you need only 5 levels of heading in the main body? Do you
need 3 levels of numbered subheading in appendices? I'm just wondering
whether Heading 6 or 7 is more appropriate for the Appendix heading. You're
in the best position to know.
> 3) Create a standard table style
Yes, of course you need a standard table style. Maybe more than one. I'm
thoroughly unimpressed with Table styles as they have been implemented in
Word 2002 and later. I would suggest you ignore them and instead create
standard tables of various types and save them as autotext entries in the
template. Then you can insert the table from the autotext entry. You can add
autotext entries to the toolbar as well as styles. Personally, I go further
than this and have VBA code that can insert a table of arbitrary size, and
format it according to my standards. The formatting part of the code can
then also be applied to a table that has been pasted in from an outside
> 4) Create a few more styles we need (a code line style, a fixme
> style for inline notes, a character style for GUI items, etc)
Absolutely. Create a style for each separate *functional* element in the
document - even if the style actually turns out to be identical in format to
another. having the functional separation makes it far easier to produce
structured documents. Also, it helps in the spearation between function and
formatting. If you decide to change the layout (e.g. because your company
decides to go through a rebranding exercise), all you need do is redefine
the styles. There won't even be a need for any retraining of the users, as
all the style names will still be the same.
> 5) Set up a title page that uses docproperty fields to display the
> date, title, version, document version, and author settings.
> Instructions on how to change the doc properties will be displayed on
> the title page, along with a reminder to delete the instructions.
Again, you could go further and create a UserForm with textbox fields for
the various docproperties. have the OK button push the entered text into the
properties and then update all fields so that the docproperty fields reflect
the latest values. Make the macro that diaplays the form available from the
toolbar. Then tell users that they edit the cover page directly on pain of
death by slow torture.
> 6) Set up standard headers that use styleref fields to display the
> document and section titles
Beware of this. If the STYLEREF field has to look back many pages,
repagination can slow to a crawl. At the very least, for the document title,
use a DOCPROPERTY field rather than a STYLEREF field. I would be hesitant to
use a STYLEREF field if the point being referred to is ever more than 10
pages back. More than 50 and I would definitely adopt another solution -
usually to insert a section break, unlink the header, and put in the new
section title as text. If necessary I would automate this in a little VBA
> 7) Set up standard footers that use our disclaimer and page
> I'll start with a clean copy of Word's normal template and recreate
> everything by hand, to avoid corruption.
Excellent. Close Word. Delete or rename normal.dot. Start Word, Go to File
New, select Blank Document, then Save As template. Use that as your base.
> I'd like to base all styles on Body Text instead of Normal, so I can do
> the make-Normal-text-purple trick that helps enforce the use of styles.
> I'd make Normal red, but some of our developers are colorblind.
> Any tips on what to watch out for?
Sounds like you are going about it in very much the right way.
Do you need to include an occasional landscape page? if so, I would
recommend you create an autotext entry of a suitable page (including the
opening and closing section breaks) with the margins, headers and footers
adjusted as appropriate. Save people the hassle of having to do it by hand
Having created the template, use the template to write a user guide on how
to use the template. You will probably find quite a few things that you need
to tweak about the template when doing this, as writing the user guide about
every feature in the template will cause you to give every feature a