Why Documentation Matters — And How To Deliver It

Guidelines For Producing Accessible Documentation

  • Internal teams, familiar with McKinsey vocabulary who are wrestling with industry-specific terminology and acronyms on their engagements.
  • External readers in the open source community may not want to learn a new lexicon at all.
  • Use short sentences and paragraphs. Google’s technical writing course recommends focusing each sentence on a single idea, converting long sentences into lists and reducing the use of extraneous words.
  • Use the active voice. The Writing in the Sciences course on Coursera demonstrates how starting sentences with “I” or “We” followed by the main verb makes the sentence a lot easier to understand.
  • Prioritise simple verb tenses (past, present, and future). Grammar Monster explains how the English language has 12 tenses, so sticking to these three can help more clearly convey whether something is a past, present, or future action. They also tell us whether the action is habitual, completed, or ongoing.
  • Don’t use present participles or gerunds. They can often just make sentences feel more clunky, less direct and harder to comprehend. Geist has a great page about this.

Accessible Documentation In Practice

--

--

--

An advanced analytics firm operating at the intersection of strategy, technology and design. www.quantumblack.com @quantumblack

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

5 Reasons Why Writers Should Learn to Code

What’s the Difference Between CCaaS and UCaaS?

Excel: text-based function

Thinking out loud about the Railway smart gates/ticketing system

Tutorial & Review: Enviro pHAT for Raspberry Pi

Forecasting multiples time-series using Prophet in parallel

iOS Stack Weekly — Issue #6

Multi Node Spark Setup on Hadoop with YARN

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
QuantumBlack, a McKinsey company

QuantumBlack, a McKinsey company

An advanced analytics firm operating at the intersection of strategy, technology and design. www.quantumblack.com @quantumblack

More from Medium

Google as a Data Science Platform — 2021 Recap

How impact-driven startups are using data to make the world better?

Usability Testing in BI- you need to know your weaknesses and fix them

5 key success factors of a modern data platform