It provides recommended readability score targets. The end result is this: for every docs PR, we get a comment posted on the PR with readability scores for each file we touch. If the first workflow actually posted the comment, it could expose the GitHub token to bad actors. The second workflow is separate for security reasons. Posts it as a comment on the pull request.Gets the workflow artifact that has the readability scores.It stores the output of our textstat scoring script as a workflow artifact. Uses textstat to score that plain text for readability.Uses docdoctor to convert the rST to plain text.Checks out files that we’ve touched in the documentation PR.I’ve set up two GitHub workflows that automate this process. With these tools, I can automate scoring our documentation PRs for readability. This gives us readability scores for everything we touch while we work. The automation that I’ve set up applies these heuristics to every file in a documentation PR. I’ve chosen two: Flesch-Kincaid Grade Level and Flesch Reading Ease. This library lets you select from 16 readability heuristics. We’re using a Python library, textstat, to do the scoring. Scoring Text for ReadabilityĪfter converting the rST to plain text, with a few minor tweaks, we can score it for readability.

So I throw out a lot of markup, and add punctuation in places, to focus scoring on the content. We really only want to be scoring the content for readability. There’s a fair amount of markup that skews the readability scores. Along the way, I make some tweaks to improve the accuracy of readability scoring. I added a command to this command-line tool to manipulate the rST to output plain text. It adds some tools on top to deal with some things that are specific to our docs toolchain. It uses another library, restructured, to parse the reStructuredText. It’s a TypeScript/ Node command line tool to manipulate rST files in our docs repositories. Docdoctor is a tool that my lead, Chris Bush, wrote. Parsing rST to Plain TextĮnter docdoctor. So I needed to be able to parse our rST to plain text. The readability scoring libraries that are currently available score markdown or plain text. There was one complication: we write our documentation in reStructuredText. So for hackathon, I decided to automate readability scoring for our documentation.

But I’ve had mixed success getting my teammates to care about readability. Improving docs readability has been a pet project of mine for a while. So if you write to an 8th grade level, you’re writing for the average American. Some sources estimate it’s even lower than that. But it might surprise you to know that the average American has a 7th to 8th grade reading level. Teams who intend to translate documentation into other languages.Įven if you aren’t targeting an international audience, simple documentation benefits everyone.People who speak English as a second language.This doesn’t consider that the density of documentation is an accessibility issue. Documentarians sometimes use the excuse that it’s “technical writing” so higher is ok.

Most technical writing comes in at 12th grade or higher. The Nielsen Norman Group advises writers target an 8th grade reading level.

Uses common vocabulary and avoids jargon.

Is scannable, with lots of clear sections and bullet points.

Readability is a huge part of what makes documentation good. Experienced documentation writers know that grammar isn’t the only important aspect of documentation.

Hemingway editor readability score