5 Golden rules for writing good project documentation

Whether it’s a statement of work, a business case, or project requirements, there are lots of documents produced by projects. And it falls to the project manager to produce most of them, or at least oversee and coordinate their production.

Documents are mainly used for communicating: upwards to senior managers, sideways to project stakeholders, and down to project team members who are responsible for delivering the work.

Successful projects need documents, so you can’t get away from them, nor would I want to. They serve a useful purpose, as long as they are clear, concise, easy to use, and fit for purpose.

If the idea of writing that next document for your project makes you shudder, then here are 5 golden rules that will hopefully make the process a little less painful.

1. Use version control

My number one top tip ever when it comes to dealing with key documents is to make sure that you use version control. This is super easy but it still surprises me how many people don’t do it.

You know when you write a document from scratch and then send it to someone for comment and then add a bit extra yourself and then someone tells you an interesting fact and you add that in and all of a sudden you’ve got 13 versions of the document in your inbox? That’s why you need version control.

Version control basics

The first version of the document you prepare is version 0.1. When you revise it for whatever reason, you change the version number to 0.2. And so on. Then you get the document approved by the relevant people so you have a final version of it. That’s version 1.0.

But the final version is never truly, absolutely, completely final, is it? Someone will want a change or there will be a formal project change raised. If it’s a small change to the document, it becomes version 1.1. If it’s a major change then rename it 2.0.

In all my time using version control I’ve never needed to count much beyond 7 in order to do this, so there really isn’t any excuse – it’s not complicated.

Read my detailed guide on how to do document version control.

Using version control numbers in documents

In practical terms, I used to use a table on the front page of the document which set out the date and the version number. This is fine for paper documents, but we don’t use paper so much anymore. That means you have to open the file to see the version number which is less convenient.

It’s better to include the version number in the file name itself (like Project Spaghetti PID_v1.3.docx). Then everyone can see at a glance what version you have in front of you and they don’t need to open files only to find out that they are looking at something that is out of date.

If you keep to a standard way of naming your files as well you can then sort them in Windows Explorer folder view (or whatever operating system you use) by name and the most recent version should pop out up the top.

2. Keep files centrally

The next golden rule for key project documents is to organize your storage.

If you have ever been in a meeting and someone has asked to see the latest something-report, then you’ll know it is supremely inconvenient not to have data stored somewhere accessible. These days there aren’t many reasons not to have central storage for files. Central storage for your project documents means everyone can look at the same versions and have access to the files.

If you are worried about people changing the files and saving over the originals then password protect them or change the permissions on your project management tools so they don’t have edit rights.

Talk to your IT team about what they can do – they might even have a solution already that you just aren’t using on your team.

Choosing the right storage option

Typically, your options for a project documentation tool are a shared network drive that everyone has been granted access to, a document storage system like Microsoft SharePoint or Teams, or a cloud-based system where all your documents are stored online.

Before you choose something yourself (and certainly before you upload any project documentation to free cloud storage systems like Dropbox) make sure that you talk to someone about what is a secure way to share files within the team.

The right storage option should link into how you want to archive documents longer term so they are useful for future projects. The project charter, project plans, and project status reports are important assets for lessons learned.

The exception: local storage for meetings

Having said all that, it is useful from time to time to have a local copy stored on your laptop. If I need to do this, for example, to make sure I have all the papers ready for a Project Board meeting, then I put them in a folder on my desktop so there’s no navigation or internet connection required – a single click and I can see everything I need.

Plus it’s easy to delete the whole folder after the meeting (only put copies in it, not your original files!).

There are also going to be some files that you will want to keep private, such as invoices for contractors’ services or other sensitive information. Store these somewhere away from prying eyes.

3. Circulate documents for comment

Nothing busts your credibility more than spelling and grammar errors (and hopefully you won’t find any in this article, either). It is also soul-destroying to get your project scope document finally approved only to find out that someone wasn’t consulted and wants to add their tuppence worth.

Try to consult widely, not just your project sponsor and immediate team. You might not agree with everyone or want to include every suggestion but as a minimum listen to the points being put forward and see if they can be accommodated in the document.

If you can’t accommodate changes from relevant stakeholders, make sure that they know that in advance of seeing the next draft and that they understand the reasons why (or they will only ask you to put their points back in).

Set up an approval process

The project documentation process should include the review phase but also clarity on who approves what. Getting documents approved can be a real challenge, so it helps to know who is responsible for each aspect.

Then you can chase them!

A note on external comms

If your document is going to an external third party you may also have to have it reviewed by your PR or external marketing team.

This is especially the case for press releases – however exciting your project, it is not your place to write press releases about it without the input from your corporate advisory team, although keen vendors may well hassle you to get one done.

4. Keep documents short

I used to write documents with a cover page, a contents page, and then a distribution list and version control table. That’s three pages before you’ve even got to the meat of the document. When you are reading that online, it is a lot of boring stuff to scroll through.

I have changed my approach. Obviously, the distribution list, contact information details, and version control information are still in there, but they are on the final page. No one except me reads them, anyway. That means you can dive straight into the juicy part of the document.

I don’t bother with a contents page anymore either unless my document is going to be huge. There’s not much point in providing signposts to something you’ll see if only you turn over or scroll down.

The shorter your document, the better it is going to be received. It’s a struggle to get some stakeholders to read through a long email, so a 16-page document is already a loser before you’ve even issued it.

The right length is how long it needs to be

Choose the right length for the type of document. Technical documentation and product documentation probably needs to be longer than an overview of your project phases and lifecycle. During the planning stages, you’ll probably be thinking through potential project risks, work breakdown structures, and more that should be documented in detail.

Later in the project lifecycle, project deliverables can be outlined at a higher level as everyone has a better understanding of what they are.

While the ‘keep it short’ rule is golden, people will make an exception for documents that need to be long. You don’t want to skimp on defining your project requirements as this will only result in miscommunications later. The trick is not to include waffle, so ditch everything you don’t need and work on the basis that even for long documents, the shorter they are the better.

5. Use executive summaries

An executive summary is a short section at the front of a document that sets out the main points discussed in the document. The executive summary is designed for the executive who doesn’t want to read the whole thing (or have time to read the whole thing). They can take the highlights from the summary and then flick forward to the bits that they are most interested in.

The executive summary is not a trailer. Ending it with: “Read on to see the full analysis and chosen recommendation” isn’t helpful. It’s a spoiler – you are supposed to reveal the ending! Tell the reader what the solution is or how much the project will cost or what you are recommending.

Don’t make your executive summary too long, either. It’s a summary, so half a page should do it. If it helps, include a graph or table but mostly you’ll find that executive summaries are short bits of text. It should be the first thing in the document after the heading and before the document’s introduction.

If you think you’ve written something that is too long, ask a colleague to read it over for you and check that it covers the salient points and is short enough to be considered a summary.

Creating effective project documentation

At the end of the day, you still have to write the document, and that means sitting down with a blank template or even a blank screen and putting words on a page. That thought paralyzes some project managers and they put it off.

(Tip: if this is you, use document templates as a starting point. It’s much easier to start editing someone else’s file than it is to craft something from a blank screen. Check out my editable project templates to get you started.)

Your document might not be perfect the first time, but at least you’ll have something. It’s a lot easier to edit a draft than it is to write something from scratch so once that initial piece of effort is out the way you’ll have input from other people to include and plenty of chances to incorporate changes in subsequent versions.

Pretty soon you’ll be a pro at producing, storing, and circulating project documents – all it takes is practice and a few of these golden rules.

A version of this article first appeared on the ESI blog in 2014. This version has been edited and updated to keep it current.