Is documentation that important?

And that is very true! Working software is way more valuable than comprehensive documentation. Manifesto allows us to make development faster and more flexible, be on the same page with the client and implement actual features rather than blindly follow outdated documents that nobody cares about when 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 a lot of time and attention. Simultaneously, there are always many other essential things to do: you can write another email, discuss some important details with the developer, meet with a client, fill in your timesheet, gag at new memes on the Internet. But what are the real circumstances of bad documentation handling?

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

Story #1. Amnesia.

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

I started looking for documents describing the feature in the issue tracker, but there were none. I asked the 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 an email about the feature, but all the details were in the attachment. However, I had no attachment as they were lost while forwarding. I was lucky enough to have contact with the first PM, and, luckily, he had kept all the emails and attachments. I got the needed document, and it clearly stated how the feature should work, and the team resolved the problem 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 the responsibility not only of project managers but developers as well. Developers should keep an eye on documents describing server credentials, development environment set up, deployment to demo/staging/production servers, etc.

Once we worked on the automatic database backups feature, the developer who made this feature was responsible for creating a document describing how it works. Still, unfortunately for us, he never did this. Backups worked just fine for a long time until they just got broken one day. The developer who made backups had been transferred to another project by that time, and the team started to look for a document describing how backups work, but we hadn't such. Eventually, we urgently interrupted the developer from his current project to help us fix the issue. Again, the price was our time that was twice or thrice more than we could've spent 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.

Projects' owners of one of our projects 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 were 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 this is described in detail in tickets, and it becomes straightforward to confirm if it's a bug or the system works as it should.

Documentation topic is vast, and it's tough to find a balance when documentation is detailed enough but 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 benefit you.

Following these simple rules will help you to resolve any issues fairly quickly and easily.

Want to get a product with clean documentation that is ready to go? We can do it!