geek-at/The-Documentation-Compendium

💡 Various templates & tips on writing high-quality documentation that people want to read.

📝 Table of Contents

It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it. Even if for some reason they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to
THE MAJORITY OF PEOPLE GLANCE AND LEAVE. Make it pretty so that it's easier for them to star before they leave. The more stars you have, the likelier it is that serious developers will use your repo
You will be using your code in 6 months. Code that you wrote 6 months ago is often indistinguishable from code that someone else has written
You want people to use your code because you think that others might find it useful. However, people need to understand why your code might be useful for them, before they decide to use it
You want people to help out. If you don’t have documentation, you will miss out on a whole class of contributors
You want to be a better writer

✔️ Things to remember:

Keep a lighthearted friendly tone. Treat the reader as someone who doesn't have a lot of knowledge about the topic but is very interested
Keep things brief
Use headings frequently. This breaks things up when reading and often it is good for linking to specific information
Link to other places in the documentation often but only for additional information. Readers should not have to navigate through several pages to find the information that they need about one specific thing. Just inline the immediately relevant information and link off if they want to know more
Use as many code snippets, CLI, etc. examples as possible. Show the reader what you mean
Gently introduce a guide before diving into technical details. This gives context and readers are more likely to stay engaged longer
It is always good to describe the functionality of the various files in your project

❌ Things you should avoid:

Don't assume prior knowledge about the topic. If you want to appeal to a large audience, then you are going to have people with very diverse backgrounds
Don't use idioms. Speak using more formal terms that are well defined. This makes it easier for non-native English speakers and for translations to be written
Don't clutter explanations with overly detailed examples
Don't use terms that are offensive to any group. There will never be a good reason to

feedmereadmes - Free README editing + feedback to make your open-source projects grow. See the README maturity model to help you keep going
maintainer.io - Free README standardization and feedback if you click on 'Book an audit'