Documentation, working software and Product Managers

I'm not sure that there’s another word in the English language that can evoke as much of an emotional reaction as “agile” — especially for those who work in software development. “It’s not agile!” might be the most overused phrase in those workplaces.?

The genesis of agile in the software world comes from the infamous Agile Manifesto. Written over 20 years ago and never updated (so not mobile friendly!), it is probably the most widely used and misunderstood set of concepts. The one value of the Agile Manifesto that I get the most visceral reaction to from the teams I work with is that of “working software over comprehensive documentation”.?

Documentation can often feel like an imposed requirement without purpose. The demand for written deliverables seems to be stronger in regulated environments, giving more credence to their clunky nature. So, if agile is such a popular way of working for companies, why is there some much documentation around? And what documentation should you create as a Product Manager?

Documents, documents documents…

What documentation am I referring to? A broad range. From (lengthy) requirements documents, to system documentation, training materials to risk assessments, RAID logs, test plans…the list goes on! Lots will find their origin in project management, and many link to milestones that were intended to measure whether the project is on track or not.?

However, as a Product Manager that is not how you measure success. You are looking at the purpose of your product and how you can translate that to value for your customers and the business. You have metrics and you are designing experiments that will help you figure out if that proposal is the right way to hit those metrics.?

So, how much documentation should you create? And which ones??

It depends ??

Why have documentation?

For me, documentation has one of three purposes in product management. The first is to help communicate an aspect of the product design. The second is to prove something happened, as a point of governance. The third, is to support clarity of thinking.?

Product Design

Look at the page you are reading this blog on. How many places can you go from this point? How many buttons? How did you get here? What colour is the font, icons etc? Even in one simple page there is a lot of complexity that needs to be communicated to many different people so it could actually make it in front of you, the user, today. Documenting all the aspects of this design into something like a clickable prototype can be really helpful to gain a common understanding across multiple stakeholders and to minimise re-work of the coding process. Like they say, a picture paints a thousand words!?And can be easier to understand when compared to describing it in words.

Obviously, as you further develop your product some of these things become standard. This is excellent and can allow for the documentation you use to adapt and become more lightweight.

Governance

The second point around governance is important, if a little frustrating, and particularly relevant for those who are building products in regulated industries. As many an auditor will say to you, unless it was written down, it didn’t happen!?

Now, the great auditors and risk professionals I have worked with don’t always mean a written document. They also do work with you to figure out how the audit point can be proven from the actual work you do. For example, our team would always note down changes made to stories in the comments section on Jira after our discussions. This helped us remember what happened and avoided repeating conversations. It pleased the auditors too!

Clarity of thinking

Oftentimes, the act of writing out your thoughts can help organise them and provide greater clarity to your design. Take this blog, for example. It is a much clearer answer to the question “why have documentation” than what you would have got from me if you asked before I wrote it.?

In my teams, when we chose to create documentation we did it with a purpose in mind. I found that writing down the key things in some format provided a great discipline to my team and value to all our stakeholders. It meant we were deliberate about points that were particularly impactful on customers from the regulator’s perspective, and stopped us moving on from a point that was not fully resolved.?

For each of these reasons, the common thread is there is a purpose. ?That purpose is understood and the documentation designed to meet that need.?

The agile clash

So, does documentation clash with agile? The short answer is no.?

The agile principle is “working software over comprehensive documentation.” Like with all the agile principles, there is value to the item on the right (documentation), but working software, the item on the left, is of greater value and should be the priority over comprehensive documentation.?

So, start with “why?” and ensure your documentation has a purpose.? Ask yourself, and your team, questions like “why have this document?”,? “does it add value?”, and “how does it help develop a great product?” You will then know how best to create and format the deliverable, while keeping overall focus on producing the working software/product and value for your customers.?

I’d recommend reading John Cutler’s excellent article “Proces v System and Habits” for a great distinction between teams that get this, and those that don’t.?

Want some help to get great systems in your Product Teams? Get in touch to see how I can help.?

The original version of this blog was published on the LogRocket Product Management blog.?

Full image credit: Photo by Carles Rabada on Unsplash