Documenting your way towards a sustainable product development

As the years go by, and I get more experienced (not to say older), I come to realize how important communication is in a company. I’ve already written a blog post connecting lack of trust and absence of communication. However, that isn’t the only consequence to that information void… Its outcomes can harm the whole business.

I could go on and on about all the communication problems that you might face, but I want to spend some time in a controversial subject: documentation.

The Agile mindset and the confirmation bias

I love Agile. Even though I prefer being agile. Either way, take a look at this Agile Manifesto excerpt:

“Working software over comprehensive documentation.”

I guess the aforementioned phrase was the most misinterpreted part of the manifesto. Actually, the whole “this over that” part was misunderstood. People forgot about the most important complementing section:

“That is, while there is value in the items on the right, we value the items on the left more.”

Most of us read the manifesto with confirmation bias, understanding that it frees us from going through the pain of documenting our work. However, as the phrase states, we still need to value the items on the right, thus not abolishing documents.

Documenting in a non-boring way

Writing documents can become tedious. Especially if you see no value on doing it. Therefore, to make it more valuable, every time you make a decision or discover something new, answer this question in your head: “If my team leaves the company today, will the product survive?”

It may seem stupid but think about it… I’ve visited companies that would strive to survive if only one person left. Is that a long-term agile company?

Why a Product Manager should care?

As a PM, I believe the product I’m working on needs to go through what we call a sustainable growth. We cannot focus just on short-term returns, without planning for the future. Hence, we need to guarantee that our product doesn’t depend on the current team (ourselves included) to evolve.

As Demian Conway said:

Documentation is a love letter you write to your future self.

So, my idea of documentation and communication goes in the same direction as I stated earlier: If I leave the job today, how much will the product suffer?

I try to communicate, share and write documents until the answer to that question changes from “it will go bankrupt” to something more cheerful. I divide the different information I have to deal with into: Problems, Stories/Bugs, and Progress.

Problems

<irony>We all know that software rarely, and I mean almost never, gives us a headache . However, we need to be prepared for when it happens </irony>. Thus, whenever a new problem is discovered, I document the following points:

What happened?
In this section, I write everything that led us to the problem we are facing. Was it a malfunction in our product? Was it a process mistake? Was it an unexpected user behavior? Did the dog bite our datacenter cables? Here we need to state all the context to that problem so, in the future, we never, ever, repeat the same mistake again.

What solutions were considered? And why we chose X?
This is my favorite section. My father used to say that you should not regret a decision made in the past based on information you only were able to have in the future. Therefore, to make sure you don’t regret it, make the decision based on all the information you have at the time, and document it.

What were the outcomes?
Well, if you solved the problem, yay! Just write down “problem solved”. However, sometimes, to not say every single time, you will face collateral effects. Some other thing will pop up, perhaps smaller, like a technical debt, maybe bigger, like another huge problem.

Stories/Bugs

Writing a good story saves us time and can act as documentation in the future. There are tons of posts out there that teach you the best way to write a story. However, I’ll leave here some suggestions on content, and not structure, that you could follow to improve communication.

Why are we doing that?
Please, discuss the whys AND write them on the task. Your team is not a team unless they know why they are doing what they are doing. Think about the motivation behind that task: will it solve a problem? Is it intended to increase our revenue? Does it decrease a business risk? Is it related to another task?

What needs to be done?
Hey, Mr. Micromanager, pay attention to the “what”, and not the “how” in the question. How things will be developed, or designed, is part of the developers/UX job. You have to trust their work. If you don’t, fix that problem before caring about how you write your stories.

An acceptance criterium that I like to put in most tasks is to build a technical documentation of that story. Sometimes, it won’t make sense to have one, but unless people say it doesn’t make sense, don’t remove it. We should account for that part when calculating the Lead Time of a story. Otherwise, if something is late, documentation will be the first thing to be postponed and, then, forgotten.

Who are the stakeholders?
This is crucial. All the teams/people that can be affected by that development, should be mentioned here. And, as soon as the team finishes the work, they should communicate it to them.

Progress

Progress is, maybe, what most PMs already care about. However, it wouldn’t hurt to add here some brief considerations about it. In our team, we have access to a writable wall in our office. Therefore we use it to document our current status and where we wanna be at the end of the quarter. If you have a remote team, you might need to use documents, spreadsheets, presentations, weekly reports or whatever you feel that passes the information around. Check this blogpost for more information on remote communication.

Here is the real picture, and a diagram, of what we draw on the wall:

What are we currently doing?
This question is covered by the areas “Kanban board” and the “week goals”. We don’t use Scrum (Kanban for the win), but we try to have weekly goals so we can improve our predictabilities and try to add more ownership over the tasks’ lead time.

What are the plans for the quarter?
We use the “quarter goals” section to continually remind the team of the direction we are headed. This helps us think if the weekly goals are helping the quarter goals, or if we are drifting away from it.

Moreover, we like to think of our board as organic, which means that it can change, and should change, over time. One example is that, in this quarter, we have a goal to decrease the number of open customer cases from X to Y. Therefore, we built a Burndown for that, to help us track if we are on the right path or if we need to shift strategies.

We also have:
• A retrospective board, to keep track of our continuous improvement tasks.
• An ideas board to not forget some excellent ideas we had but weren’t able to put in practice yet.
• An assessment board, which addresses internal feedback about our team.
• A metrics board, which reveals our throughput, lead time, the number of cases open and the number of cases opened/closed in the week.

Conclusion

We saw why documenting is important, why the PM should help and promote documentation and how we do that in our team. However, if you are just reading the introduction and the conclusion to try to understand all the things I wrote here (I don’t blame you, sometimes I do the same), just think how you could improve your work in order to optimize the answer to this question:

If you leave the company today, will the product still succeed?