Really good documentation helps users to find what they need as quickly as possible. It explains your product concepts and philosophy and builds upon existing models that your users may have. Furthermore, it gives the most information possible while taking up the least amount of your user’s time.
But figuring out how to write great documentation is challenging. As you start adding new features, your product will get more complicated to understand. And if documentation is not a priority, it will grow to be an unsustainable mass. One way to improve your documentation is to learn from great examples that already exist.
Recently, I spent some time learning about FastAPI as a python backend framework. What surprised me was how quickly I got up and running, and how easy it was to learn concepts while reading their documentation.
This article takes a look at these 5 lessons learned from analyzing their docs.
- Optimize for time to Hello World
- Start with the how and end with the why
- Make all code snippets copyable
- Separate quickstarts from advanced features
- Assume nothing
Optimize for time to Hello World
The best way to get your users excited about your product is to give them the first a-ha moment as quickly as possible. Your software might have the most interesting and innovative features, but if you can’t anchor potential customers into why your product is the solution to their problems, then you are losing
This means that no matter how important you might think some of your features are, you have to distill it down to one action item.
Let’s take a look to see how FastAPI accomplishes this.
These are the steps that are provided to get a backend server running on your local machine. There aren’t complicated configurations. There aren’t wordy instructions. There is a simple way of getting started that should work for everyone in less than a minute.
Start with the how and end with the why
Building on the previous hallmark, start with how to do something and follow-up with why you might want to do it that way. As a former developer, I’ve been frustrated with how deep I have to read into docs before I understand how to do something.
If you were to continue reading the quick-start above, you would see the author adding in a few more steps and features before going through a line-by-line explanation of every line of code you added and why it’s important.
Having a thorough breakdown of the code aggregated below the instructions as opposed to interspersed allows users to have a prototype working before needing to make changes and customize their setup. You give your users the choice to dig in deeper and understand core concepts without taking away from their product experience.
Make all code snippets copyable
If you include code snippets in your code, they need to be copyable, and they need to work. It is endlessly frustrating to use code on official documentation that doesn’t run.
But having running code is not all. Since most tutorials add new code for every step, plan on making it obvious where that code needs to go.
Take a look at this example.
The lines that are added are highlighted in a lighter blue and have a bright left border. This makes it easy for your users to know what lines to add to their code and where it belongs. This removes needless explanations of where code might be and any possible future frustrations.
Separate quick-starts from advanced features
What really impressed me about the FastAPI docs was their insight that not every feature is for every user. They showed this by splitting the user guide into two parts, a basic tutorial and an advanced guide.
As a casual user that needs to get something up and running, the tutorial might be good enough to get me to the next stage of my project. But I know that if I need something more that is a little more complicated, I know exactly where to find that.
For your power users, this helps to aggregate their needs in one spot. They may be looking to do a very specific action. By making it easy to find out if your product has a solution, you allow them to move quickly and fix their problems.
Assuming nothing about your user
What I loved about the FastAPI documentation was how explicit it is.
This is a Python function.
I love this sentence. For a developer that might not be used to Python, or even a non-coder, this tells me exactly what I need to know, or what I need to Google to learn more. The same care should be taken with the rest of your documentation. Be simple in your message and make sure that you leave the right hooks to dig in deeper.
