How I document — 7 tips for starting, writing and maintaining your documentation
Documentation is one of those topics that elicits a groan whenever it’s mentioned. We all know we need to do it, we all know we should do it, and we will get around it — after we’ve finished this task, or tomorrow, probably.
Documentation is the thing that we will do eventually. But many teams are wasting time and focus by delaying it. Ask yourself how many times you’ve answered the same question via Slack? the ticket that was delayed because we had to wait for someone to get back from vacation? Or that service that went down in the middle of the night and no-one knew how to starting fixing it? How much time was lost through all those occurrences and think through how many times a week, month, a year that is happening in your organisation?
Patrick Kua touched on the topic of documentation in one of his talks and he phrased it wonderfully:
Although, the agile manifesto preaches “Working software over comprehensive documentation” — it doesn’t preach it over no documentation.
Far too many organisations and teams continue to function through tribal knowledge. Tribal knowledge is unwritten information not widely known by many others and results in a slow pace delivery and a lower quality of the product. Good documentation is not a silver bullet to all your problems but it is an underutilised building block to get there.
Documentation can be anything; API contracts, Initiative Requirements, Business Cases or Meeting Minutes — anything that has value or meaning to others inside (or outside the organisation).
Documentation is one of those topics that elicits a groan precisely because we feel guilty for not doing it sooner. We feel guilty because we’re very aware that everything I’ve mentioned above is true. Often, the task seems overwhelming but it doesn’t have to be painful to accomplish. In this article, I share 7 tips for producing more useful documentation, faster, and embedding it into your working routine.
1. Just start —I promise this is not an easy-out answer to open the list, I mean it. Starting can be as simple as creating a new page with the title — this is the most basic building block you need. The simple act of creating a starting point can be enough for you to start filling in basic details you need to get down. The file is already open, it’s no huge step to contribute something now. Your first small win can lead you on to another — giving you a feeling of accomplishment.
2. Start simple — people are often daunted by the scope of what needs to be produced. Documentation can be extensive with introductions, glossaries, detailed descriptions, diagrams and references. However, it doesn’t all have to be there from the start. One of the many mistakes people make is feeling they have to produce everything in one go. When we build products we aim to start with an MVP — the same should be done for documentation.
Most Product Managers are now familiar with the above. It was produced by Henrik Kniberg in an attempt to explain what an MVP should actually be. A summary of the topic at hand is a good starting point — throw in a few links to other important resources (screenshots, designs) and you’ve got yourself the basics of documentation. It may just be a skateboard — but it will get them on their way.
3. Update when someone asks you a question — this is probably my biggest piece of advice on the topic of documentation. Its requires a bit more discipline but I found it dramatically improved the quality documentation I was writing and made my life easier. I discovered this tip quite by accident. One day, I was in the process of updating a page when I was asked a question by a colleague. The question was a good one and the answer wasn’t documented anywhere. Incidentally, the page I was working was actually the best place for it so I quickly added a section and sent them a link. Unrelated, a few days later someone asked me a very similar question and instead of rewriting my answer I sent them the same link again. It was that moment that I realised if someone has a question — it is likely someone else with have it too. Updating content in response to questions has additional benefits — you’re getting direct feedback from the audience on what they need so you can tailor it. Once people know where to find your (awesome) documentation, they will likely share the links and even reference it before asking you. Double win!
4. Ask others to contribute — as the old saying goes, many hands make light work. You should not be expected to solely produce every piece of documentation. Save in one-person operations, you’re going to be working in a team and there everyone has something to contribute. If there is a topic that needs adding but you don’t have the detail, ask one of your colleagues to add a paragraph or two of their expertise. I can assure you, they will likely do a better job because the content is being produced by the person that truly understands it. Similarly, if someone lets you know something is out of date — kindly ask them to amend the document with the right information. The majority of our documentation should be living — you’re not the only life-support machine around.
5. Let it grow organically — this really is the outcome of the three pieces of advice above. If something needs adding, prioritise adding that now — otherwise, keep coming back and contributing as things occur to you and when you find the time. Updating documentation should not be a laborious, several-hour task but something you can do in small chunks of time. For example, If I have a meeting finish early I will try to use that to quickly update any docs that were affected by it. This approach means you’re constantly breaking down the task into easy and manageable chunks around your existing workflows. My only exception to this method is if I am producing a diagram or drawings. These are more involved and require a higher time investment but dramatically improve the effectiveness of the document. Be sure to carve out some time for them. This leads us nicely onto Tip #6…
6. Apply formatting — this becomes even more important as a document or page gets larger. A wall of text is difficult to scan for relevant information and simply result in people asking you directly (Again). We’re not writing Shakespear — your job is to be as efficient and effective at the communication information as possible. You have a vast array of communication tools at your disposal beyond prose so be sure to use them:
- Sections & Headings — make the most of nesting content in a structured way. Add a Table of Contents to the start of the document (most tools allow you to generate these on the fly). It makes it really quick for someone to jump to the relevant section and discover their answer
- Images — a picture is worth a 1,000 words. Particularly when referencing designs or flows benefits the reader to see what you’re referencing
- Process diagrams are an excellent way of helping others understand a flow or decision tree in a way that paragraphs of text will not. Don’t forget to include a key and a clear scope so your reader knows that the diagram does or does not cover.
- Tables are perfect for displaying structured data. I often use them to support lists with multiple dimensions (e.g. outlining the project team — name, role, contact details and responsibilities).
7. Know when to prune —If you apply the tips above, your documentation is going to grow. As it does you need to know when to step in. Some sections will become outdated and need marking as such. I’m adverse from removing it entirely because older knowledge is the type most easily lost through organisational churn so I do my best to protect it. Other sections will become so large you should split them into their own documents (or sub-documents). It’s much harder to give specific examples of when you need to do this as it will depend very much on your particular case. A rough gauge, however, may be when you find people starting to ask you and the team questions about something that is already covered in your documentation — it may be there but your audience is no longer finding it accessible.
So that’s it, the 7 simple tips I use to improve the coverage and quality of the documentation for the Products I own. Since I started with this method, I have over 50 pages authored and more than300 edits on our team’s confluence space alone. But those aren’t the metrics that really matter. The real measure of success is the increasing numbers of people referencing our team’s documentation, fewer people asking us the same questions and most satisfyingly of all — individuals reaching out thanking us for the helpfulness of our docs.
This story is published in Noteworthy, where 10,000+ readers come every day to learn about the people & ideas shaping the products we love.
Follow our publication to see more product & design stories featured by the Journal team.