New Page 3

Klariti Home Page

Download Templates Online

About Us Free Tools Tips Templates Affiliates Site Map

MS Word template

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:

  1. 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.
  2. 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.
  3. 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).

Functional Requirements

Now that you have the document information set properly, it's time to start writing!

About Michael Bolton

Copyright © Michael Bolton. Visit http://www.developsense.com


Biz Templates: Proposal Template  Project Management  Employee Handbook  Procedures Business Case Process Design

IT Templates: Software Development  Testing Templates  Training Plan  User Guide Change Management Plan

Sales Templates: White Paper Case Study Business Plan Marketing Plan Cost Benefit Analysis Action Plan

$ 9.99: Acceptance Test Plan  Design Document  Requirements  Test Plan  Feasibility Study Risk Management Plan


Ads

Follow me on Twitter  Facebook  YouTube

T e m p l a t e   S h o p


Software Development Templates

T e m p l a t e   S h o p

Acceptance Test Plan

Acquisition Plan

Action Plan

Audience Analysis

Availability Plan

Bill of Materials Template

Business Case

Business Continuity Plan

Business Plan

Business Process Design

Business Requirements

Business Rules

Capacity Plan

Case Study Templates

Change Management Plan

Communication Plan

Concept Proposal

Configuration Management Plan

Conversion Plan

Concept of Operations

Cost Benefit Analysis

Data Sheet Template

Database Design Document

Deployment Plan

Design Document

Disaster Recovery

Documentation Plan

Employee Handbook

Error Message Guide

Expression of Interest

Fact Sheet Template

Feasibility Study

FAQ Template

Functional Requirements

Grant Template

Installation Plan

Interface Control Document

Invitation To Tender

Maintenance Plan

Marketing Plan

Needs Statement

Operations Guide

Policy Manual

Project Management

Project Plan

Proposal Template

Proposal Forms and Checklists

Request For Proposal

Release Notes

Risk Management Plan

Service Level Agreement

Setup Guide

Statement of Work

Software Development Templates

Software Testing (QA) Templates

Software Requirements Specification

Standard Operating Procedure

System Admin Guide

System Boundary Document

System Design

System Specifications

Security Plan

Test Plan

Technical Writing Templates

Training Plan

Transition Plan

User Guide Template

Use Case Templates

Verification Plan

White Paper Templates

How to Write

Business Documents

Case Studies

Grants Applications

Process Design

Proposals and RFPs

Project Management

Technical Documents & FrameMaker

White Papers

Writing for the Web

Business Process Templates
Project Management Templates

Standard Operating Procedures

Employee Handbook

Policy Manual

Grant Proposal

Training Plan

Statement of Work

Sponsors
 

 



Forms, Checklists, & Templates - Updated Daily

I'm Ivan Walsh, the person behind this site. I help people improve how they write, publish and extend their business assets.

You can email me here or connect with me at Twitter @ivanwalsh, Disqus, Facebook, LinkedIn, Delicious & Google.

Endorsements | About Us | Contact Us | Site Map | Privacy| License | T&Cs | FAQs | Klariti

^^^ Return to top of page ^^^