Aw Snap! The Docs, They Are A-Changin’ (with apologies to Bob Dylan)¶
Description
This presentation explores the evolution of language in technical documentation.
The reign of the long-form narrative in tech docs is long gone. Nobody wants to read a 600 page user manual cover to cover before using an application or API. Users crave bite-size chunks of information, and they want them exactly at the point of need. They want just enough information to complete their task and not one conjunction more. In other words, users want high-calorie nutrient-dense documentation, and they want it fast.
To satisfy users, we documentarians embrace minimalism and topic-based architectures such as DITA. We organize content by type: task, concept, reference, etc. We use active voice. We keep sentences short. And consciously or not, we’ve begun to challenge time-honored tech writing traditions, such as prohibitions on future tense, contractions, idioms, and colloquialisms – at least in American English documentation.
What’s more, it’s no longer enough for docs to be technically accurate. They must also use contemporary themes familiar to users and, whenever possible, humor. Exhibit one is this Google Chrome error:
“Aw Snap! Something went wrong while displaying this webpage.”
And the folks at ReadMe.io used this line to describe a Delete button in their interface (from the 2007 film, Juno):
“This is one doodle that can’t be undid, homeskillet.”
Without question, the language we use in technical documentation is changing. Contractions, idioms, and colloquialisms, which were once banned as potentially confusing to translators, are now commonplace, and we use them to make our docs sound friendlier. Jargon abounds, the word “please” is no longer taboo, and exclamation points are not only allowed, they’re encouraged! They show enthusiasm for the subject!!
In this presentation, we’ll mine the docosphere for current trends, innovations, and answers to these questions: • How has the language in tech docs evolved over the past decade, and where is it headed? • What are the minimum daily requirements for language in this brave new world: Correct grammar, complete sentences, parallel construction, proper word choice, clarity, brevity? • What is the role of humor in tech docs? • Is it OK for tech docs to use colloquialisms, idioms, contractions, and even emojis? • What are the implications of this evolution on localization?
- Conference: Write the Docs EU
- Year: 2017
About the speaker
