Write more documentation, even if no-one reads it

Who does this apply to?

This is applicable here at Cleo, and that’s the mindset I’m in when I’m putting forward these ideas, but I strongly believe that these arguments are truly applicable across all of software engineering, and probably broader than that.

‍

Why it matters to me

As an engineer and Tech Lead at Cleo, a lot of the work I do revolves around making sure the right people have the right information to make the right decision at the right time. I’ve found that by writing more and more documentation, I’ve been able to massively scale the speed at which I can convey information to other people, and to enable that to happen asynchronously.

‍

Why it matters at Cleo

Product depth

One of our Engineering Principles is that we innovate in our product, not our tech stack. This is brilliant for our customers, but it’s hard for us as engineers; we aren’t trying to answer “How can I make a high availability graphql microservice accessible via AWS Lambda”, we’re trying to answer “How hard would it be to change how the cash advance is disbursed so we can get the money users need to them, faster”. That question requires a deep understanding of the product in question, who owns it, how it’s built, and what the motivations of the company are for its future. You cannot google these things; the information is only available internally.

‍

Product speed

Another of our Engineering Principles is that we do the simple thing. Lots of small changes, released and tested quickly, to get our users what they need as close to now as we can. That, again, requires a great deal of context. What is useful, what is measured now, what is measurable, what is easy and hard to change and why.

‍

What does documentation do?

Share facts efficiently

If you write up documentation on something that is factual (describing a business approach, documenting a feature’s behaviour, or sharing a case study), when you write up the facts you can take the time to make sure they’re correct before you share them. When you share them with a new person or group, you don’t need to write up the answer again; doing it once is enough. If they have follow up questions, you can expand your documentation, or create some new documentation (that you link to from the original, to ease discovery).

‍

Share opinions accurately

If, like with this document, you want to share an opinion, you can take the time to assess your point and lay it out well; communicating in real time is fraught with opportunities for miscommunication, and “What I think X is trying to say is…” is common. Writing an opinion piece allows for a well thought out and structured starting point for a debate, and the underlying piece can easily be altered as discussion continues. If enough people agree, it can become fact.

‍

Start a conversation with a reference point

Sometimes you just want to start a conversation, and “What does everyone think about moving from Trello to Jira?” is a very vague starting point. Why are you suggesting this? What are the pros and cons? How do you want to proceed? Documenting some obvious questions can save a lot of time.

‍

Multiply your impact

If you have a conversation to share your ideas, you can only affect the people you have time to talk to. They will go on to share your ideas onwards in some cases, but they will never use your exact words, and any useful elaborations or questions and answers that happen in those conversations will not make it back to you. If you’re using documentation, those new bits of information can make it back into the document, and the sharing of information can happen completely asychronously, making information transfer much more efficient.

‍

What if nobody reads it?

That’s not going to happen.

To elaborate: In order to write documentation, at a minimum, you will read it. You’ll read it as you write, and hopefully you’ll edit it before you share it. This means that even if you don’t manage to get anyone else to read it, you’ll have organised your thoughts on the topic when you wrote it, and you can refer to it when you’re talking to people. I personally find it helpful to link to relevant sections of documentation often in my writing; if people don’t know documentation exists, they won’t go looking for it in the future.

‍

In addition to this: writing well is a skill, and one that requires practice to get better at. Every document you write will help you to hone this skill, and get better at it for the next document!