My love letter to documentation. What makes great documentation and why should you care?
Documentation is awesome
Let's get this out of the way right now. I love good documentation. I know that may sound ridiculous, but it's true. When done well, documentation is beautiful - a distilled form of communication with a clear purpose. "Oh, you need to do this thing? Good. Here is practical guide that teaches you exactly how to do it." If only life were as straightforward as this.
Great documentation shares many of the characteristics of great communication at large. There are many lessons we can learn from documentation and apply to other areas of business and life, but we'll dive more specifically into some of those lessons in the future. For now, enjoy an exploration of that excellent and wonderful, most useful communication - here it is, my love letter to documentation.
Everyone needs to document more
We all need to document more of what we do. How you accomplish your job, which you're very good at, should not be a guarded or well-kept secret. I was inspired by Courtland Allen and the team at Indie Hackers to "build in public," and this advice fits perfectly here.
As you practice clearly documenting seemingly mundane workflows or routines, you'll be practicing a lot of important communication skills. As an additional benefit, you'll think more critically about your assumptions and identify opportunities you didn't know were there.
Creating good documentation is not easy, but you'll feel unstoppable once you put the finishing touches on something that helps make people's lives easier. And, like anything else, practice makes perfect.
Let's take a look at why documentation is important, what makes great documentation, some examples, and a challenge to document more. 💌📄
Documentation is a product. The best companies in the world have incredible documentation. Regardless of industry, documentation can have an outsized impact on customer satisfaction. That new accent chair you just bought on Wayfair? The assembly instructions are going to be either a tremendous source of frustration or make you say "I'll be buying from this brand next time."
Software businesses are the same as that chair. It may be a really nice looking chair on the box, but if I don't know how to put it together then it's just firewood.
You can easily find documentation for customers and developers, but internal documentation is an unsung hero. Though rarely discussed, internal documentation is the lifeblood of a strong organization, especially at scale. 📈
Documentation perpetuates knowledge when someone leaves the company, is a critical source of information to bring new team members up to speed, and ensures everything runs smoothly day-to-day. I have, however, seen many organizations fail to apply the required rigor, attention, and investment in documenting internal processes and systems.
Internal documentation - beyond user guides
User guides are the most popular form or internal documentation, but it is important to understand that user guides are just one piece of the puzzle.
For many tasks, a simple "click here, click there" is not enough. There is often a complex set of communication steps, reviews, checkpoints, methods, mechanisms, and decisions that need to be made to complete even a basic process. This must all be captured and presented clearly, and it is not easy to get right.
But have you seen my flowchart?
Business process maps and flowcharts are useful tools, but they too are components of strong documentation, not the end state. Go to the knowledge base or "help" section of any web or mobile app you use. Although these are external documents, do you just see a series of flowcharts? No, because the context, the narrative, and the human elements are critical. These elements play an even more important role when documenting your internal stuffs because of the necessary person-to-person interaction.
Why is this important? What are the prerequisites? Who specifically do I send that to for approval? How long do they normally take to respond? What is the best way to follow up with them? Who can actually help me if something isn't working properly?
If you want truly effective documentation, you must include those seemingly "soft" elements and details. Remember, your goal is to explain something so clearly that the document alone can guide someone to understand or complete the task. The interpersonal elements must not be ignored.
There are practical financial reasons to invest your time, effort, and money in documenting everything about your work or business.
Let documentation serve as your first line of support. Generally speaking, people do not like to ask for help and will exhaust all available resources to avoid doing so. If your documentation is thoughtful and up-to-date, your customers will self-serve before admitting defeat and sending you a frustrated message on your fancy new chat pop-up.
If you're targeting consumers or have a bottoms-up strategy for B2B sales (think Slack when it started), strong documentation is a requirement in a crowded market. Take this example from Apple.
The commercial is documentation. Again, I know that Apple is largely a B2C company, but the lesson applies. Apple is the textbook example of how clear communication and usability helps you win and retain customers.
How about a freemium business model? Or that 14-day free trial? Even better. Your documentation needs to be clear and useful if you want conversions. Customers will not convert to paid users if they can't even figure out the capabilities of your product.
And you sell to large enterprise customers? You better get the technical team on board or you're not going anywhere. Developers, product managers, and senior leaders
want need good documentation. That can be the difference between closing a deal and getting a polite "thanks, but no thanks."
Don't go chasing waterfalls
Technical teams have long understood the power and necessity of good internal documentation. In fact, the "waterfall" framework for software development that has existed since the dawn of software requires full documentation and review at the end of each stage of the project.
Even the modern "agile" approach that values speed of delivery and iteration places importance on thorough documentation. The key difference is that in agile development the documentation is created collaboratively among the project team rather than a single responsible party.
No matter which methodology you use, software products require constant updates to the codebase and architecture. Every time such a change occurs, the documentation must reflect that change. Without updated documentation, teams have to spend time and money understanding the current build or troubleshooting issues with no map. And developer time is. not. cheap.
Most teams do not need to go to the extreme lengths of pausing an entire project until a certain piece of documentation is complete, but documentation is a critical part of a software release cycle.
Processes in the context of support, implementation, marketing, and other business units should be no different. If you don't have documentation, the job isn't done.
It's important I get it, but what is good documentation?
Be clear about the outcome What exactly is this teaching me or showing me how to do? Set the user up for success by making this clear as soon as possible.
Create a blueprint and use a clear structure There should be a clear outline and structure to the document. Use concise headings and provide simple navigation to different sections of the document. The more little chunks, the better. If the table of contents is as long as the document itself, you're doing it right.
Provide too much detail Be that friend who always gives one detail too many when telling a story. It is better to provide too much information than too little. Have you ever heard anyone say that a piece of documentation is "too thorough?"
Be repetitive be repetitive Use the same page and document structure wherever possible. People rely on conventions to easily navigate interfaces and will do the same in your documentation. Don't make your reader put in unnecessary effort.
You know what happens when you click a "hamburger" or "gear" icon, and your users should know what will happen when they interact with certain elements, font colors, or headings.
Think like a newbie This is the most important and most difficult guideline to follow. My approach to documentation is to always assume the reader is a novice. That means you have to think like one too. This makes the document more challenging to write, but it pays off in the end. If you only have the patience for one rule, reread this one.
But how can you just set aside your expertise to accomplish this? A good way to start is to not try at all. Just go through the process and document every step, message, email, click, meeting, ticket, or tag no matter how obvious, stupid, or simple it may seem.
Simplicity Writing in simple, clear language is never easy, but is critical in documentation. Stay away from jargon and buzzwords.
Use your whole toolbox Use everything at your disposal to get the point across clearly. Text, images, annotated screenshots, videos, gifs. No single format is better than the others. Mix and match based on what you're trying to convey. If you don't know how to use these tools, now you have an excuse to learn.
Use external resources sparingly Using backlinks that takes a user to external sites or documents is a necessary evil. You won't be able to fit everything on a single page. That said, be selective about what you backlink. Choose items that are relevant or necessary to accomplish the current goal.
Have you ever been working through a process document and ended up with three Excel spreadsheets, 17 browser tabs, and full use of two or three monitors? Me too, and it sucks. Do your best to minimize backlinks and describe the entire process start to finish.
Apply design principles Good design matters in documentation. If you get a headache when looking at a page, that's a bad sign. Hierarchy, spacing, typeface, navigation, feedback. It all plays an important role.
Documentation in the wild
✔️ Great documentation
This beautiful and incredibly thorough documentation details how Atlassian's designers and partners stay compliant with brand standards and guidelines. Atlassian checks all of the boxes here. If you want the gold standard of great documentation, look no further.
This API library documentation from Stripe illustrates how, using clever design, you can consolidate a complex process into one page that allows the user to "choose their own adventure." The only element missing is an easy way to navigate to the different headers within the page itself.
Here, Notion provides an example of all-around solid documentation. The Hershey's bar of user guides. Clear navigation at the top of the page, concise explanations, and good use of annotated screenshots and gifs.
❌ Not-so-great documentation
I know. I said that all the best software companies in the world have excellent documentation. But rules are made to be broken. Our friends at Google miss the mark on a few points here. The document requires the user to have significant prior knowledge, does not include any visual aides guide the user, has far too many link-outs for such a short explanation, and to top it all off, the text is difficult to read.
Challenge extended 🤺
Next time you are working through a process or using a piece of software at work or in your personal life, pause for a moment and think about what it would take to teach someone else how to use it. Could you do it? Give it a shot and let me know how it goes.
So, what do you think?
What was the last thing you created documentation for? Did I miss anything critical? Am I dead wrong? Do you have any stories of fantastic 😊 or terrible 😞 documentation you want to share?
Reach out on twitter and join the conversation.