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

Vaccine Booking System — Dealing with our Glastonbury

Sir Simon Stevens commenting on the busiest day for bookings

Introducing VoirStudio

Creating a dynamic database using Postgres and Sequelize.

Bash script to monitor CPU and memory usage

A Response to ‘Scrum Is Dead. All Hail Kanban, the New King’

Changes to the service

Install Windows on the external SSD/HDD for your Mac

01-Podcast

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

Why You Should Treat Your SQL Like Code

How Leaders Manage AI Projects?

Are People Becoming Lazier?

Down the Rabbit Hole, 5th December 2021