Writing good documentation is crucial. While working on Appwrite, documentation is one of the essential parts of our development life-cycle. When we are building tools designed for developers, our docs are where developers first meet our product. Complex, unclear, or unorganized documentation site can drive developers away even if your product is great. It doesn't worth a lot if your code is awesome or neat if no-one can use it.
With these thoughts on our heads, we set a list of go-to rules regarding the development of our docs site. It was extremely important for us to build docs that developers will love and find easy to both use and understand. In this post I will do my best to share some of the principles we came up with while trying to treat our docs with the same patience and dedication as we would normally treat our source-code.
1. Design & Aesthetics
Your design is the first thing developers will see when they try to deep dive into your docs. Actually, this is the first thing they see even before they read a single line of text you wrote.
You don't have to be a design guru, but you can make sure your text formatting is clear and clean. Use colors with good contrast, have enough spacing and make sure your font is readable. It's always nice to validate that your design complies with W3C accessibility guidelines.
Dark mode is also a feature developers highly appreciate, especially if they like to wear a dark sweatshirts and seat in the dark :).
2. Start at the Beginning
Think what are the most required, and un-skippable steps that a user must make to start getting value from your project. I like to count the number of steps necessary to accomplish each action and to try and optimize that number.
Remember, your docs should fulfill the need of developers checking your project for the first time and the ones that are working with it daily. Finding the right balance is crucial.
3. Understand your Target Audience
Some dev projects might target different types of developers. Have a good separation of content for different target audiences. For example, at Appwrite, we have different integrations for different development platforms.
We have integration for web, mobile, native, and backend developers. Each audience has its own getting started guide and path. We try to require minimum preliminary knowledge to align our learning curve as much as possible.
4. Headlines & Anchors
Headlines and link anchors are a great way to structure your data. Anchors will help developers to share your content easily, and headlines will allow developers that are already working with your project to jump exactly to the point where they left your docs in their last visit.
5. Think What's Next
Don't expect anyone to understand your product as well as you do. Developers' time is precious. At the end of each phase or tutorial, think about what will be the best next step for your users to take. Always think about how you can help guide them through the perfect flow in order to master your tool. This can be another doc, section, or even some external resources that might be relevant. As with every other product, try to drive action and help your users to complete multiple steps.
6. Examples, Examples, and Examples
Again, the developer time is precious. Don't waste it. Many developers will often try and skip your long text and jump right into your code examples to save time and find out whether your project is relevant for them.
Make sure to have plenty of examples for every step in your flow. Make sure your examples are simple and short as possible. No-one wants to start debugging your 300 line code or waste 15 minutes to find one single function. You developed a tool for developers to use, and its goal is probably to save them some time. Writing complex code examples will just do the opposite.
Write cohesive code examples and let each example accomplish a goal. It's also nice to have a link to a complete working script in case your code examples are highly dependent on each other. You can host the complete script on a 3rd party site like GitHub or Codepen to make your docs lighter.
7. Be Transparent
Developers are smart, treat them like that. I am writing code for over 20 years, and I don't like magic happening around me. I do want to understand what is happening in the tools I use. I do not necessarily want to know every bit of detail, but I would love to have a basic understating of the concepts under the hood. Having your code open-source is one great way to gain transparency and trust. The other is to share information about your architecture, tool stack, and design tradeoffs.
At Appwrite, we have our source-code available on GitHub, our design spec explained in our repo, and our tool stack shared on stackshare.io.
8. Don't push Advanced Topics at the Top
Simplicity is king. This phrase is right for both software and content. Make sure your docs are simple and don't require a huge learning curve or preliminary knowledge that is avoidable. Have a section for advanced topics, or at least make sure not to mix content for beginner and ninja-level developers together. Avoid throwing the heavy guns right at the start.
9. Always Iterate
Your docs will never be perfect. It might be due to lack of time, lack of initial understanding of who your audience is, or because your product shifted direction multiple times. No matter the reason, it's ok as long as you understand it, and you are constantly working to improve them.
Talk with your community, ask and answer questions, always doubt, and ask yourself what could have you done better to avoid a user issue. You can't be cohesive and yet answer every question at the same time, but you can always strive to improve and look for a better balance.
Conclusion
Writing docs is not as fun as writing code, but it's sure as important. Your docs are where the developer will meet your project and decide if it fits their needs. Good docs can help write software faster just as much as good source-code or a great API will. You should definitely dedicate the time to structure your docs to (almost) perfection.
Learn More
Appwrite is an open-source backend server that is driven by its community. You can learn more about Appwrite features, API, and integration by visiting Appwrite official website or Github repository. You can also follow Appwrite news and announcements on our Twitter or Facebook accounts. You can also chat with us on our Discord server.
About Me
My name is Eldad Fux. I am an Entrepreneur, Software Architect, open-source enthusiastic, and the creator of appwrite.io. You can follow me on my Twitter account: https://twitter.com/eldadfux or connect with me via Linkedin: https://www.linkedin.com/in/eldadfux/.
Top comments (5)
Nicely put.
These two guides go into more detail of what good docs may look like:
Eldad, can you share what your proofreading and feedback process is like?
Hey Max, thanks for sharing these resources!
Fo proofreading, we would usually take a few steps:
At the end of the day, we want to treat the docs on our site as an equal part of our product, just the same way our API or developer dashboards are.
That's gold. I reckon an extra hour you put into making better docs saves hundreds of hours across the user base. Thanks for the detailed reply!
Sure Max! Would love to see join our Discord channel so we could chat more: discord.gg/GSeTUeA
These are nice insights, as writing docs is widely an underrated skill..