The Five Principles of Writing Stuff Down
TO DOCUMENT OR NOT TO DOCUMENT? …SEEMS TO BE THE QUESTION
In the last half of 2019 while running a lot of workshops and training with folks working on improving their software development processes, I noticed I kept getting a question about how much documentation you should write, or whether should you write anything down at all, ever?
My gut feel has always been to err on the side of saying ‘none’, and then to ask people to share some of their own problems with documentation, and let them reach their own conclusions that documenting things is a cause of more problems than solutions. I’m happy to say that things called ‘Business Requirements’ are no longer considered to be a reasonable use of your time, so a document I wrote about that in 2014 is no longer so relevant. If you do still suffer with requirements documents, perhaps read this to get a breakdown of why they are a waste of your time (The irony is not lost on me here. I write things that become redundant too!).
FACE TO FACE CONVERSATIONS ARE ALWAYS BEST… UNTIL THEY’RE NOT
I’m a principled gal and I believe that the 12 principles of the Agile Manifesto was one of the most powerful things about the Agile software development movement. The principles have served me well over the years, so I still like to use them as tools for problem solving when people come at me with their questions about what to write down about what they are building, or have already built.
“The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”
Capturing the essence of something that is constantly changing and evolving into a document can be a folly, at times it feels like writing on a whiteboard is even too permanent for how fast ideas may be moving. Over time we often find that what we document begins to misrepresent the truth.
“Truth can only be found in one place: the code.”
But we may lack the skills to parse code like a compiler or we may not like having so many conversations face-to-face over and over to communicate the intention of our systems and software. That in itself may feel inefficient. Ideas and designs at times have to scale beyond single teams of code literate people, and that means you need to capture them, wrangle them into a format, so that you can share more efficiently.
SO WE DO NEED TO DOCUMENT, BUT HOW?
I sourced some answers from the internet and my twitter pals, and got back some pretty good tips. I’ve organised them here into five ‘principles’ so I can better answer that question.
So I put the question out there:
1. Less is More - The Power of a Single Page
Using a Single Page Canvas or Wiki structure can be powerful to convey a lot of information in a set structured format. It creates a useful constraint that forces you to be concise and to self-edit into just the most important facts.
“If I had more time I would have written you a shorter letter”
An anti pattern would be squashing too much in or calling it a 1 page summary when you’ve exceeded 4 pages of documentation in small font. Stick to an A3 sheet of paper rather than a digital tool, to limit how much detail you put fit in. If the topic is really rich enough to warrant more space consider an illustrated poster!
A PICTURE CAN CONVEY MORE WORDS
https://www.rebootco.com.au/relaunch
2. Every Document Needs a Customer
Every document needs a customer - If the customer of the document is yourself then - go crazy. It won’t matter if you put it in 3000 words in Evernote, A long list in Trello or your will-be-published-one-day manuscript if it’s only you that has to trawl through it. However, if you are really documenting this for others then challenge yourself to find the consumer of your document.
Once you have a customer, you have feedback. You can ask them what they need, you can even ask them face-to-face, and you might find out you don’t need to write anything down at all and a conversation will suffice. Or even better you can have the conversation at the whiteboard and that may help you design the kind of information that’s going to prove beneficial to your consumer. If you can identify the consumer of the document then you can more easily constrain it (see 1. Less is More).
Too often we set off writing documents for an imagined reader who never shows up, this is a source of waste and documentation clutter.
3. Transparent & Visual - Or, Don’t Write it Down, Write it UP!
Many times I hear of ideas that are intended to be shared between people and workplaces locked up in heads or worse, in slide decks and documents that reside inside individual laptops. If we want to create impact with our ideas or at a minimum share some important data in a way that can reach, inform and inspire others, we need to make them Transparent and Visual. I like to think of it as writing something Up, as in literally UP on a WALL so that it is instantly transparent. When we are workshopping and using post-its and sharpies we are doing this. When we use a Physical Kanban walls we are also using this power. This idea inspired a podcast episode we created called ‘Put it on a wall’. Transparent means accessible to all, anyone can inform themselves - serve themselves - by engaging in what’s on the wall. It’s a good reminder, never far from the corner of your eye that says. “Here is something important, that we all agreed was the truth”.
I have a friend working in a large department inside a very large company. She has the luxury of a full time visual designer working for their department of ~350 people. She describes the experience as making the whole department’s execution ZOOM!. Ideas are sketched up in large visual diagrams and posters that tell a clear narrative of who they are, why they exist and what they intend to conquer as goals. I was invited to tour around their base camp, a room filled with walls of visual story telling, just 15 mins was enough time to understand a huge and complex mission. A Transparent and Visual document will make your face to face conversations accelerate.
TRANSPARENT & VISUAL
The ReBoot co mini-hack podcast explains how : https://www.rebootco.com.au/podcast/2019/2/15/the-weekly-reboot-mini-hack-2-put-it-on-a-wall
4. Output Over Input - Document What You Have, Not What You Might Have
Output over Input means referencing what has been built and does exist, over things that may be built. The more permanent the solution that exists the more rich the documentation of it can be. You can apply this to decisions you have made and problems that you have (rather than the ones you imagine may come up).
I think of this one as a good companion to the Agile Principle “Working software is the primary measure of progress”. One category of thing that fits this principle well, is data. If you have statistics on usage and performance of delivered functionality it’s a powerful piece of information to capture, document and make transparent (see principle 3).
5. Consider the Destination
Where will your document end up? Where are the hidden consumers? Are they remote from your physical office? Are they ‘on the internet one day in the future’? Is this something you need to document until you reach a milestone, then it’s trash? Or do you want this quoted at your eulogy?
A consideration of the logical destination of your document will help you to match the effort you put into it, and not over do it. Sometimes you want to get something clear in your own head and test it out with a couple of people, before allowing that idea to be free, for this the roughest of sketches or even text in an email could be enough. I have been asked many times about good ways to use documents, so a couple of hours to write this blog and get the principles clear in my head and into this shareable format is a good investment of my time.
Consider not just the customer but where your document may reasonably end up and this will help you to limit or expand it to the right size, medium and channel.
***
Through these Five Principles of Writing Documentation I’ve come to appreciate that documentation is something that can coexist with improving software development teams and their processes, and I hope they help you to do the same.
A big thank you to the following wonderful Twitterati below who contributed to these principles and inspired this article.
A big warm hug to Sue Chamberlain who toured me around her team’s amazing visual workspace.
