Brainrants | Brainmates Blog

Given we all hate reading documents so much, why do I spend my life writing them? Hint. It’s not for the money.

As an analyst I don’t think it necessarily hurts that I hate reading myself. (Unless it’s fiction. I love fiction). I’ve got things to do, people to see, Netflix to watch.

We all need to be convinced it is going to be worth our while to give up our precious time to read.

And don’t get me started on 60+ page documents. Because that’s what I do. I write really, really long documents, despite my hatred of reading them!

So this is why I persist in creating the things I hate.

Don’t make me work

When working with Product Managers as a Brainmates consultant, my aim is to make their lives easier. I intimately understand just how busy so many product managers are. I have yet to work with someone whose calendar isn’t full of back-to-back meetings. Often my biggest dilemma is deciding whether or not I really need to ask to use up their lunch-time, as that’s the only free spot left in their over-packed week.

In this context, a document must add value. It’s so important to ask how a document (of all things) will make everyone’s lives a little easier?

How can I justify taking up this Product Manager’s time to tell me what they know or to review the document I’ve written? Is it worth it?

Documents 101

Starting with the basics any business analyst will tell you that there are a few key ways that documents add value.
They provide:

• Scope – what are we doing? What don’t we do?
• Structure – A good structure makes everyone work less, makes things easier to find
• Priority – Let’s do the important stuff first.
• Definition of terms – Let’s make sure we understand each other

We all know this. Right?

Panning for gold

But let’s face facts. Product managers don’t call me in when they have everything tidy. Because first, I wouldn’t be needed and second, no-one is tidy.

I’m often overwhelmed by a plethora of pieces of paper that no one has had time to pull together or keep up-to-date. In recent years, important information is often hidden away in Jira backlogs or out-of-date Confluence pages which only people on the development team can find. Thank God, Atlassian’s search function is reasonably good.

So my first justification for creating documents is to save everyone’s valuable time searching for the gold. I put it all in one place. Make sure it is up-to-date. Make it easy to find.

Getting hit by a bus

Another common experience is to find that a large proportion of a company’s intellectual property is all in people’s heads. I worry about people being hit by a bus. It’s astounding to realise how many businesses rely upon their employees crossing the road safely.

I find that the process of documenting the “As Is” gives me a framework to extract all that knowledge from people’s heads. It’s only through trying to write it down that you can identify your assumptions, and then determine if those assumptions are correct. I can’t tell you how many times I think the solution is obvious, before finding out that I had assumed wrong.

Ancient history

Maths was my favourite subject in high school, far more than history. But it’s ancient history that is the reason why my assumptions can turn out wrong.

Every company does things differently because of their history – legacy systems, legacy staff and legacy customers. There’s always a story and this isn’t obvious.

Every company needs documents which keep a record of this history, stating why things are the way they are. There are always one or two long-term employees who have the reasons in their head. As with all history, it needs to be written down. Otherwise how will the next generation know?

Assumptions make a fool out of you and me

You would think after all these years that I would not be surprised by what I learn talking to stakeholders. Every project I work on, there’ll be a moment where I believe I’ve talked to enough people to know what’s going on. Without fail there will be the “one last” meeting with some random person that will blow open a whole area I haven’t considered. It always happens.
There’s always value in talking to people.

Again, it needs to be written down. It needs to be shared. If I’m making assumptions, then you can bet that other people are too.

A picture tells a thousand words

I don’t think a document is complete without a couple of pictures.

First, because pictures help the reader to establish a shared mental model of the product with the writer.

Second, because in the process of developing a picture, I identify gaps or it helps define structure, or stakeholders, or something. This happens without fail. There’s always value in trying to draw a solution – even if sometimes the picture doesn’t make the final cut, the process still adds value.

For the people who come after you

Have you ever tried to sell a product or upgrade a product that exists in people’s heads, or on post-it notes? It’s hard. While I’m a huge fan of Agile principles, the misconception that you don’t need to document stuff has lead to so many wasted hours. One good, well structured document can save organisations so much time.

There’s lots of fake news out there. It’s important to provide people with the verified, up-to-date truth.

The only way I can face myself in the mirror each morning is to know that I am trying to leave the world a better place, making people’s lives easier.

At least I’m trying to. One document at a time.