I write a lot of documentation at work. Proposals, designs, analyses, reports, user’s manuals, engineer’s manuals — there is no end to the documentation you can write. And the most curious thing about it is that I like writing all that documentation. Years ago, like so many other people, I believed that it was heavy and ungrateful labor, but after a while, I realized two things.
I first realized the time and effort I saved by writing documentation. I was fortunate to work on software projects people wanted to use, so I always got many questions about their capabilities, how to use them, etc. It soon became apparent that it was much better to write a 15-page manual that anyone could download and read than to write lots of emails and hold endless meetings with everyone who wanted to ask me a question.
Writing documentation also helped me work remotely. A few years ago, I moved to New York while my team stayed behind in California. Every time a new person joined the team, I couldn’t sit down with them to show them where all the things were, how they worked, and answer their questions, so I wrote guides and manuals that they could read in their own time, which my teammates appreciated.
The other thing I realized is that writing documentation is not so different from the rest of our jobs. A program is a text that tells the computer how to do what I ask it to do. Documentation is the same thing but for people. Writing documentation is programming people. The industry invested so many billions in programming artificial intelligence when we’ve been programming natural intelligence for centuries.
It’s sometimes hard to write documentation, especially when we open our text editor, a blank page looks back at us, and we don’t know how to start. The goal of most documents we write for our jobs is to describe something: a design, a user’s guide, a post-mortem report, etc. If you need help writing those documents, I recommend pretending you are a journalist and answering these questions: “what,” “who,” “what for,” “why,” and “how.”
“What” is the critical point, without which the document has no purpose. It is so evident that, sometimes, authors forget about it entirely.
Not too long ago, I received an email that spent lines upon lines telling me how important a particular project was. (I’ll call that project “Bridge” to preserve its confidentiality.) Despite its evident importance, the email didn’t spend one word saying what the Bridge was, so I visited its website. The first 25% of the homepage reiterated how important the Bridge was; the next 25% announced the consequences of not using the Bridge; the following 25% laid out all the deadlines and exception protocols, and right at the end, one paragraph mentioned bodies of water and card games, but never explaining what the Bridge was.
So, never forget the “what.”
“Who” is also very important: who wrote the document, who works on the project, who this document is for, and whom to ask questions. Quite often, “who” should be answered pretty close to the beginning of the document, sometimes after “what,” and sometimes at the very top.
“What for” and “why” are very similar questions that deserve to be answered separately. “What for” asks us to explain the objective. What is the project for? What problems does it solve? What do we mean to achieve with this document? “Why” asks us to explain our motivation. Why do we need a project? Why did we choose this design? Why did we decide to write this document?
For example, imagine you invented the automobile, and you are writing its documentation. “What is it for?” It serves to carry passengers and freight. “Why?” Horses are slow and expensive to keep; trains require a lot of infrastructure; bicycles require much physical effort, etc.
Finally, I hardly need to explain “how”: it’s all about implementation details, how to use it, how to solve problems, etc.
I hope that this little scheme will help you next time the horror of the blank page strikes you.
The illustration for this Coding Sheet comes from an engraving by Jean Jacques de Boissieu.