What’s in YOUR manual?

You go to see a movie with a friend. You sit side-by-side and watch the same movie projected on the screen. Afterward, in discussing the movie, you both disagree on the motives of the lead character and even quibble over the sequence of events in the movie you just watched together.

How is it that two people having just watched the same movie could come to different conclusions and even disagree over the sequence of events that – objectively speaking – could have only happened in one way?

It’s what brains do. Memory is imperfect and every one of us has a unique set of filters and lenses through which we view the world. At best, we have a mostly useful but distorted model of the world around us. Not everyone understands this. Perhaps most people don’t understand this. It’s far more common for people – especially smart people – to believe and behave as if their model of the world is 1) accurate and 2) shared with everybody else on the planet.

Which gets me to the notion of the user manuals we all carry around in our heads about OTHER people.

Imagine a tall stack of books, some thin others very thick. On the spine of each book is the name of someone you know. The book with your partner’s name on it is particularly thick. The book with the name of your favorite barista on the spine is quite a bit thinner. Each of these books represents a manual that you have written on how the other person is supposed to behave. Your partner, for example, should know what they’re supposed to be doing to seamlessly match your model of the world. And when they don’t follow the manual, there can be hell to pay.

Same for your coworkers, other family members, even acquaintances. The manual is right there in plain sight in your head. How could they not know that they’re supposed to return your phone call within 30 minutes? It’s right there in the manual!

It seems cartoonish. But play with this point of view for a few days. Notice how many things – both positive and negative – you project onto others that are based on your version of how they should be behaving. What expectations do you have, based on the manual you wrote, for how they’re supposed to behave?

Now ask yourself, in that big stack of manuals you’ve authored for how others’ brains should work, where is your manual? If you want to improve all your relationships, toss out all of those manuals and keep only one. The one with your name on the spine. Now focus on improving that one manual.

What does Agile documentation look like?

Reading through Dusty Phillips’ second edition of “Python 3 Object-oriented Programming,” this quote caught my attention:

Further, the most important person you will ever have to communicate with is yourself. We all think we can remember the design decisions we’ve made, but there will always be the Why did I do that? moments hiding in our future. If we keep the scraps of papers we did our initial diagramming on when we started a design, we’ll eventually find them a useful reference.

That strikes me as a good benchmark for acceptable documentation in Agile. Whether coder, UI/UX designer, data architect, or whatever, if you are keeping a good record of what you decided and why, you’ll probably be able to recreate the rationale for why things got to be the way they are for anybody who needs to know. Especially if that anybody is you. And there is a good chance that someone following in your footsteps will be able to pick up the same rationale even in your absence. All this without putting an unnecessary burden on project progress for the sake of detailed documentation.

Of course, what qualifies as “good” is the tricky part. A suggested threshold would be to specify only as much information as makes sense or for what is known given the current situation. Documentation should be subject to iterative practices just as much as code.