Hi James:
This is never going to be "easy" because the document's logical structure is
not... Ummm.... "logical"
The problem we have here is that you are mixing apples and pears. You want
them all to be "green" (i.e. "numbered") but you want different shades of
"green" that look exactly the same. Well, you can do this with colours, but
you can't do it with numbers
Somehow, you have to tell the reader "There are two kinds of 'thing' in this
document." There are "headings" that act as labels for sections of text,
and there are "paragraphs" that contain information.
You "can" do what you want, and the others have suggested methods for doing
so. I will suggest another: ListNum fields (look them up in the Help). But
you wanted something that's "simple for unskilled users to maintain".
That's your real problem
You have a virtually unmaintainable document
structure. It's the sort of thing they pay highly-skilled technical writers
to maintain, because it uses at least SIX sequences (Headings, Paragraphs,
Numbered Lists, Bulleted Lists, Figures, Tables...) and two are nested
multi-level.
Now: There's your problem
Since YOU got the job (What DID you do
wrong??) that's the first thing you have to fix. You have to go back to the
authorities and say "The typographic style chosen for this document prevents
anyone from using it successfully or maintaining it correctly. That's
because we are using the same 'indicators' for two different classes of
object. Now, I can do what I am told, and you can tell me to keep doing it.
But as a documentation professional, it is my responsibility to write this
in a memo and send it to you, so that you have been formally notified of a
defect in our product. And I need you to file the memo carefully, so that
when (not if...) some event occurs that results in major damage to the
customers and/or shareholders, and the enquiry takes place, you and I can
demonstrate that we did our job: we notified management that they were
creating procedure documentation that we knew would fail if anyone tried to
use it."
Down here in Australia, Exxon blew up a Gas Plant (several billion dollars
worth) doing this. In Bhopal in India, someone poisoned large parts of a
city. And at Three Mile Island... Well, United States citizens are keenly
aware of what happened there...
A document that is designed to go wrong will go wrong. And when official
documents go wrong, they do it in a big way. When those TV lights light up
all over the nation, you want that memo on file to make sure they're not
pointing at YOU
Now: How to fix it
First, we need to separate the Headings from the
Text. The first thing we need to do is ensure that we do not have
INFORMATION in the Headings. Headings are "labels" or "sign-posts". They
can have other uses in a newspaper, but this is not a newspaper, we need to
be clear about that! In a technical document, we need the headings to be
"labels" ("This is the bit that says what Electricians are responsible
for"). And we need them to be Signposts ("You are in the Responsibilities
section, among the Tradespeople's responsibilities, getting close to the
Electrician's responsibilities").
One reason we want to remove "information" from Headings is that information
changes all the time, and we would rather our signposts didn't do that. Can
you imagine taking a taxi someplace if we renamed the streets every month?
One good way to do this is to remove the numbers from the Headings. It
makes it easier for the reader, too. If you send the reader to "Section
3.5.1.8" his first question is going to be "Where the hell is that?" If you
send him to "Electrician's Responsibilities on Page 128", he instantly knows
"that's one-and-a-half thumbfuls down the book". And (trust me, I've been
doing this 30 years...) "thumbfuls" is the way readers REALLY navigate paper
documents
You tell me this document is going to be presented to the readers in any
other way than on paper, and I suggest that my argument becomes even more
important. Numbered sections work badly on paper, but they don't work AT
ALL on a website.
So let's get rid of the numbering off those headings. Given the headings
you've shown us, if you simply do that, your headings will work just fine as
headings. The numbering is actually serving simply as visual pollution,
getting in the reader's way, confusing them, and causing them to forget what
they're about to read the minute they've read it.
Once you un-number the headings, the rest of your problem becomes trivial.
Now, the ONLY things that have "numbers" are the "information paragraphs".
Immediately, the reader can distinguish between the navigation paragraphs
that help him get where he's going, and the information paragraphs that you
want him to read. He can tell at a glance the difference between the
"street signs" that allow him to find the street he wants, and the "street"
he wants to walk along.
And because you now have only one numbering structure, you no longer have
multilevel lists nested within multilevel lists. You have only one
multilevel structure (your paragraphs) and all the other numbered series are
single level and not nested in anything.
You can then make some simple rules for the unskilled users who will
actually have to write the content! "Each content procedure begins with a
Heading 3 that says who its for and what it is. For example: Electrician's
Responsibilities".
The paragraph immediately below that must always be an Overview of the
information in your section. Write it last of all (when you know exactly
what you have put in the section) and use the Overview Style for it.
Then add a Procedure heading for each procedure you are going to include;
begin each with the name of the procedure, and style each with Heading 4.
For example: "Safe Working Procedure".
Within each procedure, write the steps as separate paragraphs, and format
them with the Step Numbered style, which will automatically number them
correctly for you...
And so on.
Notice how you can now describe what you want the writers to do, simply and
clearly, with no loop-backs, if's, but's, or "exceptions"? That way, you
have a fighting chance that they will do it
(If your instructions to
normal business-level workers in a corporation exceed 1 page of 12-point
type, forget it: they simply won't DO it. Re-design your process and start
again!
Oh, by the way... If you really do want to hang onto the existing design,
then do it with ListNum fields. You CAN'T do it with the Outline Numbering
feature, because your structure requires nested multilevel outlines, which
is something Word's Outline Numbering is designed to prevent (if you force
it, you corrupt the document). You can do it with ListNum fields or SEQ
fields. ListNum fields are a bit of work to set up, and you will never get
ordinary users to use them properly. But they're easy enough to understand,
stable, and automatic
SEQ fields give you ultimate flexibility, but
they're a lot of work to set up and they do not update automatically. They
are very rugged and reliable, but you will never explain them to ordinary
users in a million years: they simply don't have time for the explanation,
so don't try...
Hope this helps
==intro==
Most of the documents that I've read at my company are entirely written
using the style "Header". (Yes, that's "Header" not "Heading".) Since these
are operating procedure and work instruction documents, I thought they could
be reformated with Styles (so I can enable Outline view) and insert Table of
Contents for the larger documents. Unfortunately, thier numbering system is
doesn't make sense to me... almost every paragraph is numbered, whether they
are headings or merely steps or body text.
==question (part 1)==
How do I format the document so I automatically generate the Table of
Contents, but can omit some paragraphs from the TOC? or change the entry in
the TOC for that heading? (Word 2000)
Here's an example:
1.0 PURPOSE:
1.1 To establish and maintain a documented system ...
2.0 SCOPE:
2.1 Applies to any records, hardcopy or electronic, ...
2.2 Applies to all records maintained by us...
3.0 RESPONSIBILITY
3.1 All employees are responsible for:
3.1.1 Ensuring all records are legible and readily identifiable.
3.1.2 Following the procedures detailed in this SOP...
Note: All employees must blah blah blah...
3.2 Quality and Regulatory Affairs is responsible for:
etc...
Obviously, I can put 1.0, 2.0, 3.0, etc as Heading 1. But what about 1.1,
2.1, 2.2? Those are not headings, whereas 3.1, 3.2 should obvioulsy be
formatted as Heading 2. 3.1.1, 3.1.2, 6.2.1, etc are not headings either,
but later in the document, say, 6.5.1 Retention of Records will be a heading
and have substeps 6.5.1.1, 6.5.1.1; which may or may not be headings
themselves.
I want to include most of the top level headings, and have alternate TOC
entries or omitted entries for the non-headings.
Ideally, the TOC would look like
1.0 PURPOSE
2.0 SCOPE
3.0 RESPONSIBILITY
3.1 All Employees Responsibility
3.2 QRA Responsibility
3.3 ...
4.0 ...
(i.e. omit 1.1 non-headings, revise the headings of 3.1 & 3.2, and omit
3.1.1, 3.1.2, etc.)
==question (part 2)==
Here's the hard part. How do I make it easy? I need to make this easy for
people who have trouble with Paragraph formatting. Do I need to fiddle with
VBA to make macros?
--
Please reply to the newsgroup to maintain the thread. Please do not email
me unless I ask you to.
John McGhie <
[email protected]>
Microsoft MVP, Word and Word for Macintosh. Consultant Technical Writer
Sydney, Australia +61 (0) 4 1209 1410
