You are visitor number ????? since 20 April 2001.
Go to Howard Kaikow's home page

Standards and other technical documents

This discussion will apply to most any document, however, my emphasis will be on the use of Microsoft Word for the creation and updating of technical documents such as standards and product specifications.

The creation of such a document is usually an iterative process, involving modifying the document several times over a period of several months, even years, to produce the final specification. This can be a very tedious and ineffective process if one does not take advantage of the automatic numbering capabilities provided by Microsoft Word.

There will likely be a need to revise the specification months, or years, later. Revision is expedited by using the automatic numbering capabilities provided by Microsoft Word

My goal is to suggest some things and hope that editors of such documents use these suggestions to improve the situation.

Cross references

A document should never contain a hard coded cross reference, i.e., always use symbolic references using, say a REF field or an INCLUDETEXT Field.

I continue to see standards published using Microsoft Word documents that use only (or predominantly) hard coded cross references. This significantly increases the cost of correcting, or updating, the standard.

Using macros can facilitate the conversion of hard coded references to symbolic references. I've done this for a few standards. Unfortunately, the process cannot be totally automated and verification is, at best, tedious

Heading 1-9 styles

Applying to inappropriate paragraphs

Heading 1-9 styles must never be used for anything other than paragraphs intended to be numbered using Microsoft Word’s automatic numbering of such paragraphs.

If the styles are applied to other types of paragraphs, there is a problem if one needs to create an automatically generated table of contents using the TOC field.

Hard Coding Heading Numbering

If one wants to hard code numbering in paragraphs, do not do that using the Heading 1-9 styles. Such paragraphs can still be included in a table of contents by using the \t option in the TOC field.

However, such hard coding, be it with Heading 1-9 styles or not, causes a significant difficulty in modifying a document. I’ve seen published standards that have gaps in numbering, corresponding incorrect TOC entries and, if used in conjunction with hard coded references, well, ‘nuff said.

Numbering of clauses in an Annex or Appendix

One of the great shortcomings of Microsoft Word has been the difficulty of using Heading Numbering in both the body and Annexes of a document. I find that this is one of the reasons some get led astray in using Heading 1-9 styles.

I describe a clean solution in Numbering of clauses using SEQ fields in an Annex (This is a zipped Word document)..