Some tools for better documentation

If i had to make a top three of the most important factors regarding user documentation, this would be my list:

  1. Audience
  2. Searchability
  3. Readibility

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.

hemmingway

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.

JS1

And this is what it came up with:

  1. 1:5-1:14boogeyman may be insensitive, use boogey instead
  2. 1:42-1:48master / slaves may be insensitive, use primary / replica instead
  3. 1:61-1:63he may be insensitive, use they, it instead
  4. 1:79-1:84Don’t use fucks, it’s profane
  5. 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…

Geef een reactie

Vul je gegevens in of klik op een icoon om in te loggen.

WordPress.com logo

Je reageert onder je WordPress.com account. Log uit /  Bijwerken )

Google photo

Je reageert onder je Google account. Log uit /  Bijwerken )

Twitter-afbeelding

Je reageert onder je Twitter account. Log uit /  Bijwerken )

Facebook foto

Je reageert onder je Facebook account. Log uit /  Bijwerken )

Verbinden met %s

Blog op WordPress.com.

Omhoog ↑

%d bloggers liken dit: