WriteTheDocs 2017 – The Docs, They Are A-Changin’

Speaker: Kate Wilcox

Has the language used in documentation changed?

  • Some things stay the same: passive voice is still out, and clear, concise documentation is still the best.
  • Language has become less formal: Replacing "enables" with "lets", "data are" with "data is", "ensure" with make sure", etc.
  • More idioms are used, including pop culture references

Of course, different rules and styles apply for different types of documentation, and company, and environment.

Have style guides changed?

Let's look at the Microsoft Manual of Style for Technical Publications, which has grown about 40 pages per publication over four publications.

It features different spellings, and gained a nicer tone.

  • Use questions sparingly
  • Don't try to be funny
  • Use contractions to create a more familiar/friendly atmosphere
  • Use ! sparingly
  • Omit needless words.

What do other writers say/feel?

A survey produced a very different approaches to style, including DITA/topic based, minimalist, long-form narrative, Chicago/MS MOS …

Examples

Questions

Old school: don't, newer: use sparingly. Examples show introductory questions leading users into the text, approaching the users with empathy and engaging them.

Humor

Old school: Don't, newer: "don't try to be funny". Humor becomes dated easily and can be misunderstood, but it also can make content memorable. We should also distinguish between negative humor (including put-downs) and positive humor. Negative humor should definitely always be avoided.

Contractions, exclamations, emojis

Old school: Don't, newer: contractions are ok, exclamations sparingly, which mirrors current usage. Contractions are used to use a familiar tone, exclamations aswell.

Idioms, fictional references etc

Idioms are still used very sparingly. Keep in mind that this makes software feel foreign and inacceptible to non-native speakers. Fictional references may be used in examples, but it is best use sparingly.

Takeaway

Styles are changing to be more approachable. Needless words are included, language innovations accepted, but some rules still apply (such as being concise or not using passive voice). Further research in topics such as localization and local flavours of these changes is needed.