Sometimes you may feel that your documentation, article, or post lacks something. You may see people lost while reading your texts. You may get too many questions about things that - you're sure - you've included in a guide or an e-mail. Where is the reason for this?
Do you know React only as a front-end library? Have you ever thought: "React documentation rules!"?. Well, I have. And here is why.
Compare your texts to the below list based on React documentation and check if you can make your writing better and your readers happier!
1. Self-explanatory subtitles
Let the readers scan the text so they can easily find what they need. Avoid these shrouded in mystery subheadings like “Your mum taught you to clean up after yourself” when you just want to tell about clearing an interval in the componentWillUnmount() method.
Here is a perfect example. You wouldn't even need a Ctrl+F shortcut to find a paragraph about the Custom Hook. You would just find it while scrolling.
2. Lists and stickout keywords
When there is too much "dense text" we lose interest, we lose focus. And when there are no visible keywords we can't even find an appropriate piece of information. It takes more time to work through. See an unordered list and highlighted keywords below.
But don't overdo keyword marking. It may cause an opposite effect like in this article about white space ;)
3. Links
Give your readers some useful additional information so they don’t have to search for it on their own. Provide links or a short explanation.
4. Transparent guidance
Guide the readers. Make sure they always know where they are and what they should do next.
Here is an example of providing additional information and guiding the reader to the next section.
5. Important information and tips
Where there is a really important or useful piece of information make it stand out. Use different color, font or put them into a frame.
6. Warnings
When you know some frequently made mistakes, write them down. One doesn’t always have to learn from their mistakes.
7. White space
Care for your readers’ eyes. Remember about a nice amount of space between subtitles, lines, list items, etc. You will find an example of a good white space amount on each screenshot in this article.
8. Possibility to experiment with code
Your readers would be absolutely thrilled when you provide a possibility to try the code out - on CodePen for example.
9. Lack of spelling and punctuation mistakes
Mistakes can change the meaning of the whole sentence. Some mistake-sensitive readers may be put off the stride and may lose their train of thought. Check your text before publishing!
Now take your post, article, or piece of documentation that you've recently written and check it with those 9 tips. Can you make your text better?
Good luck!
Top comments (0)