Is documentation that important?

In this article I want to share my experience with project documentation and day-to-day operations. Is documentation that important and why?

At the beginning I’d like to take a look to our beloved agile manifesto, which says:

…we have come to value:

Working software over comprehensive documentation

And that is very true! Working software is way more valuable then comprehensive documentation. Manifesto allows us make development faster and more flexible, be on the same page with client and implement actual features rather than blindly follow some outdated documents that nobody cares about at the time development is finished.

However we often face a temptation to treat the manifesto as follows:

Working software over documentation

Or even:

Working software over any documentation

Not many of us love writing documentation. I don’t. Documentation demands lot of time and attention, while there’s always lots of other important things to do: you can write another email, discuss some important details with developer, meet with a client, fill in your timesheet, gag at new memes on Internet. But what are real circumstances of bad documentation handling?

I want to bring couple of real cases from our company practice to show you why documentation is indeed important.

Story #1. Amnesia.

When I just started working I got my first project with long history, and in addition to documentation in issue tracker I got forwarded ton of emails for year and a half, these emails had all the decisions made during development. Everything was going smoothly until the moment I got email from the client saying that one of features works completely wrong and it’s surprising that it’s on production server.

I started looking for documents describing feature in issue tracker, but there was none. I asked previous PM and it appeared that there definitely should be a document describing the feature, I just need to dig for it. Then I started searching for it in emails, and indeed I found and email about the feature, but all the details were in attachment. However I had no any attachment as they were lost while forwarding. I was lucky enough to have contact of the very first PM and that he had kept all the emails and attachments. I got needed document and it clearly stated how feature should work and problem was resolved quickly after.

What was the price of it? Time. I could’ve spent twice or thrice less time on finding the answer if we had all the documents in one place.

Story #2. Some technical stuff.

Documentation is responsibility not only for project managers, but developers as well. Developers should keep an eye on documents describing servers credentials, development environment set up, deployment to demo/staging/production servers, etc.

Once we were working on automatic database backups feature. Developer who made this feature was responsible to create a doc describing how it works but unfortunately for us he never did this. Backups worked just fine for a long time until they just got broken one day. Developer who made backups was transferred to another project by that time and the team started to look for document describing how backups work but we haven’t such. Eventually we had to urgently interrupt developer from his current project so he could help us with fixing the issue. And again the price was our time that was twice or thrice more then we could spend if we had just one tiny document.

Story #3. When everything is fine.

Not to spam you with negative examples here is another one when documentation is up to date, bright and shiny.

On one of our projects project owners change fairly often, and every new PO starts to learn the product, tries to find how to improve it, tests it for unknown bugs. And during that time we’re receiving dozens of messages about possible bugs. But we have a simple way to check this — documentation! It’s not hard to find answers to almost any behavior questions, as it’s described detailed enough in tickets, and it becomes really easy to confirm if it’s bug or system works as it should.

Documentation topic is huge and it’s really hard to find a balance when documentation is detailed enough and not comprehensive yet.

Few basic hints:

- to keep documentation in one place. Don’t leave important decisions or discussions in messengers, emails, talks;

- keep an eye on technical documentation, it should be updated regularly;

- don’t hesitate to spend your time on documentation, it will always benefits you.

Following these simple rules will help you to resolve many issues fairly quickly and easy.