If i had to make a top three of the most important factors regarding user documentation, this would be my list:
In another blog i will go deeper into this choice. This little blog will be about number three; tools to improve readibility.
The rules of the game are clear: avoid complexity, stear clear of the passive voice, avoid the use of adverbs, write short sentences.
Proofreading might help, but using a specific tool is a better alternative.
The first tool is called Hemmingway. after the writer known for his simplicity and short sentences. This tool grades your writing and comes up with improvements. I copied the text from an arbitrary blog.
Integration into tools like MadCap Flare, Author-It, Paligo and other Help Authoring Tools would be much appreciated by many.
The second tool is Alexjs. It is built to catch insensitive and inconsiderate writing. The API, server and network documentation seem to be the targeted area. I am not a big fan of this initiative. It is ‘Don’t call..someone might be offended.’ An example below.
And this is what it came up with:
boogeymanmay be insensitive, use
slavesmay be insensitive, use
hemay be insensitive, use
- 1:79-1:84Don’t use
fucks, it’s profane
- 1:104-1:110Don’t use
slaves, it’s profane
I predict a wide use of the Hemmingway tool and a limited use of the Alexjs initiative.
Any comments welcome…