write-the-docs-prague-2017-aw-snap-the-docs-they-are-a-changin-by-kate-wilcox.json

{
  "abstract": "This presentation explores the evolution of language in technical\ndocumentation.\n\nThe reign of the long-form narrative in tech docs is long gone. Nobody\nwants to read a 600 page user manual cover to cover before using an\napplication or API. Users crave bite-size chunks of information, and\nthey want them exactly at the point of need. They want just enough\ninformation to complete their task and not one conjunction more. In\nother words, users want high-calorie nutrient-dense documentation, and\nthey want it fast.\n\nTo satisfy users, we documentarians embrace minimalism and topic-based\narchitectures such as DITA. We organize content by type: task, concept,\nreference, etc. We use active voice. We keep sentences short. And\nconsciously or not, we\u2019ve begun to challenge time-honored tech writing\ntraditions, such as prohibitions on future tense, contractions, idioms,\nand colloquialisms \u2013 at least in American English documentation.\n\nWhat\u2019s more, it\u2019s no longer enough for docs to be technically accurate.\nThey must also use contemporary themes familiar to users and, whenever\npossible, humor. Exhibit one is this Google Chrome error:\n\n\u201cAw Snap! Something went wrong while displaying this webpage.\u201d\n\nAnd the folks at ReadMe.io used this line to describe a Delete button in\ntheir interface (from the 2007 film, Juno):\n\n\u201cThis is one doodle that can\u2019t be undid, homeskillet.\u201d\n\nWithout question, the language we use in technical documentation is\nchanging. Contractions, idioms, and colloquialisms, which were once\nbanned as potentially confusing to translators, are now commonplace, and\nwe use them to make our docs sound friendlier. Jargon abounds, the word\n\u201cplease\u201d is no longer taboo, and exclamation points are not only\nallowed, they\u2019re encouraged! They show enthusiasm for the subject!!\n\nIn this presentation, we\u2019ll mine the docosphere for current trends,\ninnovations, and answers to these questions: \u2022 How has the language in\ntech docs evolved over the past decade, and where is it headed? \u2022 What\nare the minimum daily requirements for language in this brave new world:\nCorrect grammar, complete sentences, parallel construction, proper word\nchoice, clarity, brevity? \u2022 What is the role of humor in tech docs? \u2022 Is\nit OK for tech docs to use colloquialisms, idioms, contractions, and\neven emojis? \u2022 What are the implications of this evolution on\nlocalization?\n",
  "copyright_text": null,
  "description": "",
  "duration": 1816,
  "language": "eng",
  "recorded": "2017-09-11",
  "related_urls": [
    {
      "label": "Conference schedule",
      "url": "http://www.writethedocs.org/conf/eu/2017/schedule/"
    }
  ],
  "speakers": [
    "Kate Wilcox"
  ],
  "tags": [],
  "thumbnail_url": "https://i.ytimg.com/vi/DYgw6xcpDmE/maxresdefault.jpg",
  "title": "Aw Snap!  The Docs, They Are A-Changin\u2019 (with apologies to Bob Dylan)",
  "videos": [
    {
      "type": "youtube",
      "url": "https://www.youtube.com/watch?v=DYgw6xcpDmE"
    }
  ]
}