7 Tips To Improve the Format of Technical Documents

By Michael Bolton
In order to make sure that your document can be navigated easily, there are a few basic features that it should include.
A lot of my work as a consultant, program manager, programmer, and technical writer entails trafficking in documents. Documents are very useful.
A written document leaves much less to chance than an over- the-shoulder conversation between two people in a hallway.

A document can be saved, retrieved, published, circulated, discussed, consulted, and archived. Documents can take the form of specifications, procedures, memoranda, histories, or letters of complaint.

Software Development (SDLC) Templates

Even source code files are documents. A document can be used to inform others of your great new product idea, or to help defend yourself in a lawsuit. Most importantly, a document can be used as a contract--a record of an agreement between people about what shall be done, and the terms under which it shall be done.
Like a good Web page or a good roadmap, a good document contains meta-information--information that helps you understand things about the document itself, rather than its content.
Here are a few of the essentials in creating a document that will help to speed things up, rather than slow things down.
Irrespective of the content, every useful document should have:

A title. This should appear on the cover page of the document (if there is one) or at the top of the first page. A title helps to make sure that everyone is referring to the same document, and that everyone knows the general subject under discussion.
The author's name. If someone wants to comment on a paper, to whom should the comment go? And besides: if you wrote it, you did some useful work -- take credit for it.
The file name. When it comes time to revise the document, you're going to need to be able to find it.
A date. Documents get revised all the time; a date stamp ensures that everyone reading is in synch with everyone else.
A draft number. A date alone won't cut it. Alas, in the fast- moving computer software biz, there may be more than one revision of a document on a single day.
An abstract. This is anything from a quick sentence to a paragraph describing the content, scope, and intended audience for the document. This sets the expectations of the reader, and helps to make the purpose of the document clear.
A running footer at the bottom of the page. The running footer contains important information about the document. This information should include:
- A page number. How many of us have spent pointless hours in meetings saying things like "No... not that page... the one after that... look here -- the page that begins with '...and an unripe watermelon.'"
- A total number of pages to accompany the page number. It's much easier that way to tell if you're missing the last five pages of the document.
- The document's title and author. This makes it a lot easier to sort things at the network printer, or if there's a pile of unstapled documents on the table.
- The revision date and, if possible, the draft number -- to help explain why your page 6 and my page 6 are different, and which one of us has the current version.
- An indication if it's a confidential or copyrighted document.

Now: who has the time to set all this up for each document? Well, why bother when you can get a machine to do it for you? If you use Microsoft Word, the attached document template which I have named Standard.dot will allow you to do almost all of the housework automatically.

Use Case Templates

Each time you wish to create a new document, there are three even simpler steps:

Choose Word's File / New option from the menu bar. Due to an inconsistency (I believe it to be a bug) in Word, Ctrl-N, the keyboard shortcut for creating a new file, does not display a choice of document templates, so use File / New instead. One of the templates displayed will be "Standard". Choose this template.
Before you do anything else with the document, choose File / Properties from the menu bar. Under the Summary tab, edit the Title and Author fields to reflect the title of the document and your name.
Replace the abstract provided with one that reflects the content of your document.

The document information is set up for you, and so is your running footer. In fact, everything is set up except for the draft number; that you have to do manually when you finish and release a new draft. (There is a Word field that tracks the draft number, but this number is incremented every time you save the file. Draft numbers would never be the same twice, and would run into the hundreds fairly quickly.)
Your fields will update automatically before printing, but to update them manually (so that you can see what they look like), hit Ctrl-A (Select All), and then F9 (Update).