How to Create Consistent Documentation

If you find yourself cringing at the thought of looking for a document for your project, you are not alone.  It can be difficult to manage all the documents that are created for a project such as business requirements, system requirements and design documents and then to deal with everyone’s writing styles, formatting and organization.

I have been challenged in my shop with the following:

  • Identifying the “official” document. Is it someone’s notes or the system requirements?
  • The “Official” document has been lost or edited.
  • The “Official” Document has been copied and everyone is using a different version.
  • The Documents vary greatly in structure based on the author.

Below are my strategies for dealing with these problems.

Standardize your “Official” Documents

 Standardizing documents can create an easy way for all users of the documents to know what is official.  A project can produce hundreds of documents both official and unofficial, such as developer notes, BPA research, emails, requirements and design.  With all those documents, how would a tester, trainer or developer know what documents are the ones to pay attention to? Standardizing official documents helps everyone understand what is important.  The following are basic criteria for standards I like to use.  It allows freedom to create while having a consistent feel.

Cover Page

Create a standard cover page that has this basic information

  • Project Number and Title
  • Date of Creation of Document
  • Author
  • Last Modified Date

Table of Contents

The Table of Contents should tell the story.  If you read the table of contents and don’t have an idea of all the main components of your project, then your document is not organized well.

Headers and Footers

The header should show your organization information and logo on the Left side, with your department on the right.  The footer should always contain page numbers (x of y preferable) on the right.  On the left you might want to have the location of the document, unless people who use it do not have access to that directory.  The project number and name is nice or document type.

Heading 1

for table of contents – These Headings are your table of contents and should give an outline of your project.

Heading 2

for content – Also part of the table of contents but should help the reader understand subcategories of your project.  No other heading levels should be added.  Use bullet points, charts, matrices and pictures to explain the rest.

Create Headings for Required Content

If you have certain topics that must be discussed in your document, for example, in a design document you may need a section on Data Base Changes or Validations.  A System Requirements Document may need a section about Scope.  Just be sure you create a separate template for each so you don’t have the requirements writer trying to create content for the Data Base Changes section.

 Don’t Allow Copies

People love to make their own copies of the documentation.  Don’t allow it.  If the document is updated they will not see the changes.  Instead do the following:

Make the Document Read Only

Make all official documents read only and password protected for saving changes.  This will save you from the headache of people accidentally updating the document or dragging it to a different folder without realizing it.

Add the Link to The Document in emails

When distributing official documents via email do not attach the document unless the email recipient does not have access to the document.  Users will notoriously bring the wrong version to the meeting or even code or test from the old document.  Send the link to the document instead and briefly outline the changes in the email.

Version the document and Update the Modified Date

Before any meetings, include the link and let everyone know which version of the document to bring and it’s and modified date.

What Not to Do

  • Don’t allow documents that are not official documents to have the header and footer and other items that make the document official.
  • Don’t allow documents that ramble on or have redundant information. Read more on this in my post Break Up Documents for Better Focus.

Finally

Standardizing your documents can bring organization to chaos and foster a more professional look for your documents that will show your customers that you take the work seriously.  It will also, stop the confusion for which documents are official.  Read more about storing your documentation in my post entitled, How to Organize Your Project Documentation.
https://forms.convertkit.com/266300?v=6

Get the Charter!

Join in and get the Simplified Project Charter free today.

We won't send you spam. Unsubscribe at any time.

3 thoughts on “How to Create Consistent Documentation

  1. Hi Cheryl, good article and I’ve had my share of fun over the years with project documentation. The extra recommendation I’d make is that people run the new templates past the people who are going to be getting them when they are completed.

Leave a Reply

Your email address will not be published. Required fields are marked *