Technical Documentation using Templates and Styles

Creating technical documentation for a project is often the last thing that project developers and application engineers think of. The impression that nobody reads the documentation anyway has led much of the industry to put little time into good documentation. As a project begins to come to a close, they turn the writing chore over to a "Technical Writer" who turns the directions given by programers into simple how to instructions. Often as not, these how to instructions fall short, either using language that is inappropriately scientific to the user, or through documents poorly formatted and almost impossible to read.

A few simple techniques available on every word processor and publisher can change the creation of technical documents from a difficult and ungainly task to something that is simple to read and easy to understand.

Styles and Templates

No matter what word processing program you use, styles and templates work identically.

A style is a collection of formatting attributes applied to characters, paragraphs, or documents. Formatting items with styles ensures consistent formatting throughout a document. Whenever you change the formatting in a style, you change the appearance of all items that use that style. You can, for instance, change heading fonts, point sizes only once and have the changes applied throughout your document.

A template is a preformatted document that can be used as a guide for creating a new document. Templates are valuable when creating documentation, to give manual a uniform look. A template contains all paragraph, heading and font styles that you intend to use in your documentation.

Combining the styles with a template allows you to create project templates that define exactly how you want your project to look. Microsoft Word, Corel's Word Perfect, PageMaker and other programs all use templates and styles to format whole documents. Matter what word processor you use, you can make documents that are easy to read.

Determine the Final Format of Your Manual

The exact look of your document is determined by the format that you will use for it. Printed manuals will be formatted differently than web documents or help files. Once you have decided which format the final product will take you can then set up your project templates.

At this point you want to know if your manual is a printed document, help file or html. Help files have unique considerations but follow most formatting used with paper manuals. HTML documents are somewhat limited in styles by the medium.

Set the Margins

Margins are used in paper manuals and help files. If you are using a paper manual, know how big the manul will be. Set the paper accordingly and set you margins so that all of your text will be printed in the useful area of the page. Margins are not set for html documents.

Set the Font and point size of the body text in your document

Start with a blank page. Go to the styles editor for your word processor or publisher program and find the style used by text. Some use None as the default text. Its attributes are set by you in preferences. Most of the time you will also find "Normal" or "Body" text styles. Which style you use is not important, so long as you are consistent. If you choose to call your text, body text, then keep it that way throughout your document.

Determine the normal font and point size used in your document. The exact point size of the text will be different depending on the font. Times New Roman 12 pont text appears as a different size from Arial 12 point text. Arial appears larger, has few flourishes and is easier to read, copy or scan. The main concern is with the amount of space on a page taken up by your text. You can put far more information with a smaller point size, but it gets much harder to read. A 12 point courier font is considered ideal throughout the printing industry, but the actual size of the text is an item of preference.

Set your justification style

Justification or Left justification are the most common. Justified text looks neater on a page. You should be aware that left justified text has been found to be easier to read and less fatiguing to the eye.

Format your Paragraphs

There are two other major considerations for the body text, indenting and paragraph spacing.

In fiction and formal writing an indent is used in the first line, generally five spaces. Technical manuals do not indent. Generally paragraph spacing is used to separate paragraphs in technical manuals, most often 1.5 lines. However this is not a rule written in stone. The major consideration, again, is consistency. Set the format of your paragraph, either indented or with paragraph spacing.

Setting the Point Size and Using Fonts

Heading in a manual have two purposes. The first is to set of specific sections of your manual, and the second is to give the structure of an outline to make finding specific parts of your documentation easy.

Go back to your styles editor for your word processor or publisher program and select the first heading, by default named heading 1. Heading 1 will be the largest heading used in a manual or other document, and is used for you most general headings, such as Chapter or Section Names. You can use any point size, but a good guideline is to use a Heading 1 point size no larger than twice your body text. In the case above, with Arial 12 point text you would make your heading:

Next go to Heading 2 and make it two points small, 22 points. Using a gap of two point sizes makes the different sized headings instantly recognizable.

Fonts can also be used to differentiate your headings. By making your heading a different font or font style you draw attention to the words. You should try making your Headings a different font entirely than the body text. If, for instance, you are using Times New Roman for your body text, use Arial or other distinct font for your headings. One thing to remember is that you should never use elaborate script styles that are difficult to read.

Running Header and Footers

Headers and Footers are running text or page numbers found at the top and bottom of the page. Page numbers are, most often, placed at the bottom of the page. A running header that contains the product name and section or chapter title are most often found at the top.

The running headers are ideal to help your manual user find information fast. They should never be large enough to confuse them with a header. Ideally, they should be in the same font or, at most, one or two points sizes larger than body text and bolded. Set a distance of at least two lines between the body nearest body text and the running headers and footers so as not to confuse your reader.

Save Your Project Template

Save your project template. Depending on the Word Processor the exacts steps can be different, and they are generally given a different extension. Microsoft Word uses *.dot files while Word Perfect uses *.wpt.

When ever you begin a new project open up the template and begin working. Every document will be formatted in the same way every time with very little work or fuss.