90 Percent

Project management, productivity, change management, and more!

7 tips for a well documented project



Source: dhester

A project without documentation is a sure path towards problems. Whether it’s a few documents for a small project, or a great amount of documents for a large project, documentation is important to make sure relevant information is available when needed to complete the project.

Keep in mind that the goal is to have information available for your team when they need it, so having documentation is important, but it must be organized too. Here are several tips to help you with all this:

1. Document everything that’s important

A lot of information is transferred during a project, whether it’s oral or written. It’s important to note everything that is relevant to the project.

For example, every meeting should be documented into “meeting-minutes” and sent to everyone. That way, everyone can refer to those conversations, and that will avoid terrible conflicts in the future.

At the same time, too much useless documentation is not going to help. The important information will get lost amongst the rest. Make sure you note what is useful for the project. If you are unsure, then have special locations for secondary information. For example, have a separate section at the end of your document that list miscellaneous information just in case. Just make sure it doesn’t get in the way.

2. Keep it accurate

Your documentation is like your project’s instruction manual. If the information is wrong, then it’ll bring your project to disaster. Have it double-checked by colleagues to make sure everything is perfect, or if your colleagues documents some parts of it, then make sure you validate everything.

Even if just a small portion of the information is unreliable, then the team will stop referring to ALL the documentation since they won’t trust it.

3. Keep it updated

This complements the previous point. Non-updated information is the same as not accurate information. This means that it can bring your project in the wrong direction and can have colleagues lose trust in your documents.

Always keep it updated as soon as new information is available.

4. Format for easy reading

If your documentation is hard to read, or too time-wasting because it’s awfully long, people will not read it or will waste a lot of time finding the information they need.

Read my article on TMI when communicating is just as bad as not enough for more information.

5. Make it easy to find

It’s so easy sometimes to transfer the information in several mails here and there, not gathering it all at the same place. What happens when you do that? You end up with lost information, or it’s scattered everywhere and you waste time finding it.

Instead, have one place where you store all documentation, including simple quick information like a FAQ for your project (people will have questions, and answers will be forgotten!). If you always use the same logic with your projects, and organize them the same way, your team (even you) will find the information more quickly. Time will be saved and everyone will appreciate it.

6. Avoid duplicates

There are rarely any good reasons to have the same information documented more than once. If so, try analyzing if you could document differently to avoid this.

What can happen if you duplicate information is:

  • You waste time documenting more than once, and you will waste the same time updating the information afterwards; and
  • Adds the possibility of error; if the duplicates are not maintained correctly, it may lead to confusion.

7. Keep versions

Keeping versions is important if you have to go back to validate information, or answer questions you may have. Documents are not going to take too much space on a hard-drive, so keep versions, just in case.

Name your documents correctly when numbering them; version 2 should be used over version 1. I’ve worked with colleagues to whom numbers didn’t matter, and version 1 was to be used instead of version 2 or 3. Guess what happened? We often used the wrong documents and lost hours. It’s very frustrating so be nice to your team, use the right numbers 🙂

In conclusion

A well documented project simply runs better overall. It does take some time to do this correctly, but the time you and your team save is more than worth it: Less confusion, less wasted time looking for information, fewer errors,etc.

Do you have any tips to add? Have you had good/bad experiences with documentation in past projects? Please share!

2 thoughts on “7 tips for a well documented project

  1. Indeed, project documents must be relevant (tip #1), accurate (#2), maintained (#3), readable (#4), accessible (#5), centralized (#6) and version-managed (#7) because these attributes are what makes project documentation useful. But I’ve got two questions for you to reach beyond this first statement :

    1. What’s the methodology you use to satisfy these seven quality attributes?
    2. What’s your take on the challenges software development teams encounter while trying to satisfy these attributes? What are these challenges, why are they failed and what can be done to overcome these failures?

    Of course, I don’t expect you to answer these big, overarching questions in one comment reply; consider these as food for your future, more in-depth posts!

    • Thanks for the feedback.

      Very good questions, although yes the answer could be a whole new article, I still want to give you a brief answer:
      1- To be completely honest, I do not use any specific methodologies. If one should be named, I guess you could say it’s inspired from the Lean methodology of avoiding waste (ex. Too much information). What I do is that all those recommendations into consideration when I create my document templates, but what’s more important is always improving them as I go on. This includes gathering feedback from colleagues or from myself (ex. Was it simple enough that I was motivated to update everything?).

      2- Their are several challenges and many reasons it doesn’t work, without getting too much into details, here are some brief examples:

      Challenges: documenting the right information and not everything, making sure it’s clear for the others and not just us,etc.
      Why does it fail: people complicate documents (too long, hard to read), therefore it is not motivating at all to read them, nor to update them, making everything a complete waste

      What can be done: Do more with less! Sometimes 3 or 4 words can say as much as 3 or 4 sentences.

      Thanks for the inspiration, I’ll make sure to write another article on the subject.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s