5 Project Documentation Mistakes You Are Making

Having worked with a diverse group of people in various industries, I have dealt with a lot of project documentation of varying types, ranging from user requirements and system design to scope of work and project charter. More often than not, mistakes are unavoidable (we are humans after all!) but some mistakes just shouldn’t be repeated. Here are the top five mistakes that I often encountered in project documentation:

1.  Inconsistencies

Inconsistencies in (any type of) document are very common. While it is understandable that you are overwhelmed with a lot of work and you are hard-pressed for time, but these inconsistencies can have negative impact on you, the project and the company. These six types of document irregularities are the most prevalent ones:

(a) Different types of company logo design are used

On the front cover of a proposal, Type 1 logo is used. But on subsequent pages, oh my… Type 2 logo is used on the header / footer! Technology evolves.  So does company logo. If you are unsure of whether your company has changed its logo, you can either check with your company’s branding team (or guideline in the company’s portal) or visit your own company’s official website to see if there is any change. Ultimately, you need to decide and use only one type.

logo evolution

(b) Figure captions are irregular and ambiguous  

A picture is worth a thousand words. The adage is true, so much so that it can be confusing to the readers as to what it exactly means if the picture does not have a descriptive caption since it is open to the readers’ own interpretation. What seems like a system upgrade procedure to a solution architect may look like decommissioning of an existing system and purchase of a new hardware to a project manager. Some images in the document have proper figure captions and some don’t. Some captions start with a set of numbering and some don’t. You need to get rid of these irregularities and leave no room for ambiguities!

(c) Use of both American and British languages

The spellings for certain words vary between American and British languages. You should only use either one but not both. If you are employed by an American company and you are preparing a document for internal company use, then use American English. You can also check with the company’s official guideline on this. However, if you are preparing a document for a client whose company is locally established in Malaysia, then use British English (since Malaysia was a former British colony). Usually, for large projects, the official use of language is stated in the project governance document. In the example below, both types of languages are used, but it seems that American English is the more dominant one:


(d) Different table designs and lack of table captions

In one page, a grey-theme table is used but in another page, a blue-theme table is used. Scroll down further, and you will see these two themes are used interchangeably throughout the document. To make matters worse, some tables have proper table captions and some don’t! Stick to one theme (unless you are trying to create a colourful document for a Colour-Me-Contest!) Similar to figure captions, tables in a document should have concise descriptions too.


(e) Date format is not standardised

16-Jun? 16th June 2014? 16 June 2014? 16-Jun-14? June 16th? June 16, 2014? 16/06/2014? The format type seems endless! When there is a need to indicate dates in the document, decide on one format and use it consistently throughout the document. In fact, some large projects have a project governance document that dictates the type of date format to be used.

(f) Bulleted list with complete and incomplete sentence

One of the hotly debated arguments among the English Grammarians is the use of complete and incomplete sentence when creating a bulleted list in a document. I kid you not. Google up on this topic and you will find a plethora of discussions about which one is right or wrong. Well, as a general rule of thumb, if you start off the bulleted list with a complete sentence, then use complete sentences for the rest of the bullet items.  Likewise, if you start off with incomplete, i.e. point-like sentences, then make sure the remaining bullet items are in point-like sentences.


2.  Page numbering not updated

Pagination errors normally occur especially after each section break in a document where the next page number is not updated accordingly. This is often overlooked and can be confusing and frustrating to the readers. Be sure to do a courtesy check on the page numbering after every new section break that you create.


3.  Manual Table of Contents (TOC)

You’ve got to be kidding if you are still creating the TOC line by line! It is very tedious and time-consuming to manually update the affected page number (or the section title) every time you make changes to a document! Highly unproductive! Use the TOC built-in feature in Word to help you do this.


4.  “Document Change History” section not updated accordingly

The “Document Change History” (also known as “Version Control”) section is important as it records both minor and major amendments to the document. You will know what is the latest version of the document, when it was last amended and what are the changes made to the document. Unfortunately, this crucial section is often overlooked and it could be confusing to the team who will do a peer review later on. There is also a risk that you could be sending the wrong version with outdated information to the client. Do put in a little effort into updating this section and tersely describe the changes.


5.  Copy-and-paste blunders

There are just so many instances of such careless act that I have come across and one outstanding scenario had me go “OOOHHHH NNNOOO” (perhaps the longest “OH” and “NO” I have ever muttered in my life). A solution architect reused a document from a previous project (let’s say Project Gas) where he copied and pasted the information for another new project (let’s call it Project GLC). After he had updated the document and sent it to me for a quality check…my oh my…I noticed that the server hostnames in several tables bear a striking resemblance to a large project that I had previously worked on in another company (yes, I worked long enough in that project to remember the naming convention of the hostnames!) I immediately clarified with both the solution architect and the assigned project manager and true enough, it was purely a copy and paste mistake…a serious mistake, I had to say!

The list of mistakes can unroll like a ball of yarn, but if you put in a little more effort and pay some attention to detail, you could have avoided these pitfalls and rip the rewarding benefits of good documentation practice.

Leave a Reply

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