Keep Your Sentences Short

Mike’s professional discussions

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.

Last modified January.01.0001