Documentation is a Communications Vehicle

I’ve seen very large product requirements documents in my day, and I’ve even joked about the size of some of these documents, holding them in one hand and stating, “These must be great, they weigh a lot!” Heavyweight documentation doesn’t imply thoroughness. In fact, it can mean that you may have a couple of problems:

1. The scope of the project is too large.
2. The person writing a large volume may not be an effective communicator, at least not in written form.

Smaller projects have been proven to be more successful than large projects. It is extremely difficult for people to keep their heads wrapped around the intricacies and nuances of all the desired behaviors in large-scale systems, especially at the outset. I’m an advocate of starting small and building into it. When I see a large binder, I worry. These days, I start asking to see something smaller.

Creating a clear, succinct product requirements document requires someone to roll up their sleeves and truly engage in the process. You need people who can take a lot of inputs, work through the contradictions that always emerge, and express the needs in both words and diagrams. This takes a lot of work, requiring someone with both good verbal and written communication skills. This certainly isn’t for everyone.

And while the product requirements document itself may be a deliverable, it isn’t the final destination, either. It is only one step in the journey to produce working software. The product requirements document is vehicle for communication.

In the beginning, it serves as a catalyst for communication. No product manager should build a product requirements document in a vacuum, there need to be conversations with customers and stakeholders alike. As you move forward, the product requirements document becomes a record of needs, market conditions, decisions made, explanations of different facets of the market and the product relationship to the market and customer needs.

On the opposite side of the coin, some people translate the Agile Manifesto’s value of valuing working software over comprehensive documentation to mean “no documentation.” While conversation is a good thing, it pays to write some things down. A product requirements document helps sort through a lot of background thinking before any work even gets to a development team.

When it comes to writing things down, the philosophy of user stories being “reminders to have a conversation” will be counter-productive if people dismiss the concept of capturing critical outputs that result from the conversation. I don’t like having the same conversation over and over with the same people because we failed to take adequate notes.

If you are adding items to a product backlog – perhaps further down in priority than other items, you will need supporting material to refer back to when the story is groomed and eventually pulled into the team’s sprint. And there are plenty of times in the Agile world where priorities shift and you don’t get back to the conversation until much later, so it pays to attach a note to remind yourself and the team of any decisions made, or issues and concerns raised that will need to be addressed with the user story.

I’ve also been in user story workshops where we’ve captured the business need in a user story, but felt that additional information was required. We attached that information as notes to the user story so we wouldn’t forget critical information later. This information became acceptance criteria in some cases, while other information served as a basis for a child story.

In the software world documentation plays a supporting role, and one that should not be ignored. How many times has the act of writing something down clarified your thinking on a particular subject? Used wisely, documentation can boost productivity. Conversely, if it is over-used, it can drain productivity.