#How to write a good docs

Writing documentation is difficult, exhausting, and often time-consuming. Maintaining a docs can be also challenging. Since the documentation itself isn't the top priority of a product or library, we don't have too much time to maintain the docs. Writing a good documentation is not as simple as it sounds, it can be a strenuous job as your project grows.

#Learn from Feedback

As a non-native English speaker, it's extremely hard to explain a complex idea or an abstract concept even in my native language. I'm also learning from user feedback and suggestions to improve my content.

You can provide a way for readers to leave feedback and suggestions to the docs. With these suggestions, you can address the problems in your content sooner and easier.


Markdown, especially GitHub flavoured Markdown (GFM) is a common format for docs. You can leverage it to create a better experience for readers:

After WorkWatch anime

#Writing Style

When reading blog posts, people love poetic and beautiful wording. It gives a different vibe to readers and make the article vibrant. However, most docs readers are not native English speakers, especially the readers of programming framework and library documentations. Most importantly, you really don't need fancy wordings for a docs.

You should use:

#Pages Organization

Organizing pages and navigation elements can be more important than your content. Browsing a site also include navigating between pages. No matter what documentation framework you choose, you should provide Document Search, and a navigation element like Sidebar.

As you make changes to the library/product, your content may become out-of-date or incorrect. A better organization of pages can mitigate the problem, and reduce efforts to maintain the content.

Leerob's blog post also gave great suggestions about this.

#Page Organization

Since most people start learning basic writing skills in elementary school, I assume you can organize different sections/headings, and paragraphs correctly.

Deciding what to put into a page can also be difficult:

Last Updated: