8 hints for keeping your project well documented

Rafał Broll
Dec 16, 2016 · 6 min read

During every project a lot of knowledge is “stored” in team members brains. Unfortunately, human memory is not the safest place to keep valuable information and that’s why you have to secure the project knowledge “on paper” (of course you will use computer for that). In this article I’ll try to give some hints that I’ve found reasonable for the 3 most common types of documents.

You could apply the advice below to many other types of artifacts. You might find some of it useful, the rest — not so much. It depends on your process and needs — the decision is up to you.

#1 Don’t treat documentation as something created in the meantime and without any costs.

As I work in a software development outsourcing company, I frequently talk to the clients who think that documentation is an activity that has lowest priority and can be created in the meantime. That’s the first mistake. Of course there are projects with such a short life-time where documentation might be a pure waste of valuable project resources, but in other cases the lack of it is often a root of all knowledge management problems in the project. To leverage all the benefits of a well maintained documentation you have to treat it like a full-fledged output product. The same as in case of source code development; you need to allocate enough time, skills and attention in order to create a useful documentation. You should consider it in your budget or just skip it entirely if you don’t need it.

#2 Think about users and their needs.

This tip might sound like a no-brainer, yet when working on such abstract projects as software it is very easy to wander off the right track. Before you start, try to predict who and when will need the knowledge transfer you’d like to share. Don’t try to give huge pile of details at once just because it’s easier that way. Here are some questions I use to keep my focus:

  • What language should I use? Is the user a technician, developer, programmer or a business person?
  • What goals will the user want to achieve when reading this document?
  • Did I give enough information to achieve those goals?
  • Is it useful and accessible?
  • How much effort will I need to put to reflect the changes in the project and maintain the document?
  • What will be the optimal structure to avoid the need of reading all the pages just to be sure that you haven’t missed any important information.

A hint to the last one: the table of content is just the beginning, but you could go further and equip your documentation with additional indexes (it’s nothing special to have multiple indexes in database systems — why not use it in the documentation?).

#3 Diagrams and charts are awesome.

No doubt, we are visual creatures. That’s why it is always easier for us to grasp new concepts by looking at the colorful shapes, rather than reading pages of small letters. Moreover, diagrams are extremely useful in presenting knowledge on high levels of abstraction.

There are standards which provide guidelines on how to create diagrams, like UML or BPML. You will surely find them useful and they help you create great diagrams. Remember not to end up a diagram-specification-nazi. If you feel limited by the standards, be creative, extend them or even go completely freestyle to make them work for you. Use colors and possibility to organize things logically in 2-dimensional space. The only things that matters is to make the document as pleasant to read as possible.

#4 Control the level of details.

Is the reader always interested in all the details and quirks? Think about the user and his needs. Always try to find what level of detail they will need to achieve the goals. Of course such approach has some drawbacks — you will probably need to duplicate some information and write it down several times with varying level of detail. That means you will have more information to track and maintain when something changes in the project, yet from my experience it is better to put some extra effort to gain much more — useful documentation.

#5 Don’t try to fit the template at all costs.

Every project has it’s own profile and scale. That’s why every one of them requires special treatment. Sometimes it will be good to divide documentation into modules, other times it will be better to revolve around user types or permission levels. To find the approach that is the most convenient for users, you should get started with a Minimum Viable Product: try to deliver a small (but valuable) prototype and gather feedback from your teammates.

Don’t get me wrong. Templates can speed up the process.. Just don’t try to fit into them at all costs.

#6 Make it part of the process.

The best way to enforce maintenance of good and updated documentation is to apply it into your development process, as soon as possible. In such a case the document will not be invented just to meet your contracts but it will be a result of a real, everyday need and will be instantly verified on the ‘battlefield’.

For example at UX Dream we see that involving Quality Assurance in taking care of requirements documentation works really well:

  • testers motivate developers to cover the documentation, so it’s their interest to keep this document up-to-date if they want to deliver the right product.
  • testers have to know what to test so they need knowledge about what should be delivered in the final product,
  • testers have to protect the product against regression (regression = unexpected bug emerged in original set of features after modification or introducing a new feature), so they need to maintain exact register of all features,
  • putting testers as closest as possible to the source of requirements helps to reduce the risk of turning Project Manager into the only source of true. It happens quite often in small companies and causes a situation in which nothing can be delivered to the customer without acceptance of Project Manager. It shouldn’t be they responsibility!

Such approach is very naturally becoming part of the process as it is in the best interest of the QA to keep the requirements complete, precise and updated.

#7 Learn and invest in your software engineering toolbox.

Software engineering is recognized as a separate branch of computer science. There’s a lot of interesting publications on the subject. Expand your toolbox, learn new methodologies and get familiar with good practices. That way you will have broader perspective of possible approaches and easier choose the ones that fit your projects. Here’s some basic knowledge:

When comes to requirements you can divide them into functional (features) and non-functional (quality):

  • Functional requirements strongly depends on the project so there is no generic template. However, software engineering proposes some forms of requirements description: Use cases, mock-ups, user stories + definition of done (be aware that user story without exact definition of done is just an invitation for further discussion, however it can be the right form for basic description of the project features).
  • Non-functional requirements were described in ISO 25010 standard that proposes a closed list of areas like: software security, safety of usage, maintenance, service availability, recoverability, availability for user, performance, interoperability, extendability, etc…

Software architecture is even more complicated (it strongly depends on project type and scale) but we can also find some systematic approach, the 4+1 Architectural View Model proposes describing the software architecture in 4 aspects, each one for different reader:

  • Logical (user, business stakeholder),
  • Process (integrator, system analyst, database engineer)
  • Physical (system administrator, integrator),
  • Development (software developers)

Each of those aspects is supposed to be connected with Use Cases (that’s the ‚+1’ layer) taken from requirement specification which should guarantee the full coverage of requirements by system architecture.

#8 Do you really need it?

Let’s finish with a small plot twist. Remember that you will need to put in a lot of effort to create useful documentation and you will also have to keep it up-to-date constantly. Otherwise readers won’t trust your documentation and will just stop use it. Having outdated documentation might even bring you more harm than not having one.

Project documentation have a lot advantages but the decision about whether to document your project should be taken carefully and knowingly after analyzing all the gains and losses. It doesn’t have to be a binary decision: if maintaining a documentation of everything is too costly, you can always reduce the scope of the documented knowledge to the most needed minimum.


Providing reliable software development outsourcing solutions. Custom-made web and mobile applications.

Thanks to Krzysztof Lewicki

Rafał Broll

Written by



Providing reliable software development outsourcing solutions. Custom-made web and mobile applications.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade