Keep Your Sentences Short

Readability can make all the difference. When developers look at competitive products, the first thing they look at is the docs. I’ve seen it make a difference in sales.

Readable content can reduce frustration. If developers have to think about words when reading docs, will they even bother trying out the software?

When I work on readability, one thing I work on is sentence length.

As noted by MIT (http://web.mit.edu/juggler/www/ocw/ocw_lectures/class01/lecture_shorten_sentences.htm):

No one really wants to read long sentences in technical prose--they are visually intimidating.

But with limited time, how do you find those long sentences? Many companies are using Vale (https://vale.sh) to help.

To see what’s used, look for the sentenceLength.yml file. Here’s an example on one version of the file I worked on for GitLab

Is 25 words the right limit? I don’t know. When I evaluated (~1000 word) security articles for anohter company, I’d typically find a half-dozen sentences which were too long.