DEV Community

Eldad A. Fux for Appwrite

Posted on • Updated on

9 Tips to Help You Improve the Most Underrated Skill in the Tech Industry

Photo by Patrick Tomasso on Unsplash

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

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.


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 You can follow me on my Twitter account: or connect with me via Linkedin:

Discussion (5)

rimutaka profile image

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?

eldadfux profile image
Eldad A. Fux Author

Hey Max, thanks for sharing these resources!

Fo proofreading, we would usually take a few steps:

  1. Defining docs KPIs/Goals to measure success, some examples:
    • What are we trying to make the reader achieve?
    • How much time should it take to complete the goal?
    • How many steps are required for success? can we reduce any?
    • How many iterations did the user need?
    • Were we right with our assumptions about preliminary knowledge necessary to achieve the document goal?
  2. Trying to follow the docs ourself, this will be by the author itself (not that trivial as it may seem :))
  3. Sharing the doc with teammates and even better, developers from our community.
  4. Having a feedback loop as long as possible, honestly, this might be affected by time constraints a lot of the time, but we try and do our best to make the process as useful as possible.
  5. Most of the time, we'll use a beta stage that might take weeks to help us gain more feedback from a wider audience.
  6. We will monitor the usage of our docs, just like a media company will monitor its content consumption (read time, user funnel, bounce rate, etc..).

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.

rimutaka profile image

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!

Thread Thread
eldadfux profile image
Eldad A. Fux Author

Sure Max! Would love to see join our Discord channel so we could chat more:

madza profile image

These are nice insights, as writing docs is widely an underrated skill..