DEV Community

Cover image for You wouldn’t expect to learn this from React documentation!
AnnaBuller
AnnaBuller

Posted on

You wouldn’t expect to learn this from React documentation!

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.

A self-explanatory subtitle in React documentation saying: Extraction od Custom Hook

A self-explanatory subtitle. The screenshot comes from: https://reactjs.org/docs/hooks-custom.html

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.

A screenshot with highlighted keywords and a bullet list

An example of a list and noticeable keywords. The screenshot comes from: https://reactjs.org/docs/higher-order-components.html

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.

A screenshot with a highlighted link and "what to do next" information

The end of a chapter with a useful link and a "what to do next" piece of information. The screenshot comes from: https://reactjs.org/docs/add-react-to-a-website.html

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.

A visible piece of useful information named as a "Note"

A visible note with additional explanation. The screenshot comes from: https://reactjs.org/docs/hooks-state.html

6. Warnings

When you know some frequently made mistakes, write them down. One doesn’t always have to learn from their mistakes.

A stickout note with warning against a popular mistake

A stickout warning. The screenshot comes from: https://reactjs.org/docs/react-component.html#constructor

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.

A code snippet with a possibility to try the code out on CodePen

A code snippet with a possibility to try the code out on CodePen. The screenshot comes from: https://reactjs.org/docs/lists-and-keys.html

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)