Jimee, Jackie, Tom & Asha, CC BY-SA 2.0 https://creativecommons.org/licenses/by-sa/2.0, via Wikimedia Commons

A focus of mine over the last few years has been how new users for software are enabled by good documentation, or conversely how easy it is to inadvertently put people off with the language you use. There are countless articles on this, around the use of terms such as “just”, or “simply”, and I’ve made observations myself on other examples over the last couple of years. However, I recently read a series of articles (kicked off by this one from Julia Evans) that made me realise that the debate is actually more nuanced than I had considered, and that there are downsides to using language that’s too simple.

Avoid Jargon #

You don’t want to put off complete beginners by overwhelming them with unfamiliar jargon, but avoiding necessary technical terms will be counter-productive in the long-term, as it will be a barrier to further searching and learning. A good balance would be to avoid unnecessary jargon, but introduce vital technical terms with a friendly explanation.

For example, here are three ways of introducing the same concept, namely making a change to some documentation for a project that is hosted on GitHub. Note I have omitted some elements of the process in step three, for brevity. Don’t @ me.

1. All jargon: Submit changes to our documentation by forking the repository and submitting a pull-request.

2. No jargon: Submit changes to our documentation by copying the code and sending us a version with your changes in it.

3. Friendly explanation: To submit changes to our documentation, firstly you’ll need a user account on GitHub. Then make a copy (or fork) our repository under your own account, make the changes there using the in-built text editor, and then submit a request back to us (a pull request). We will review your suggestions and hopefully approve them. If you are unclear about any of these steps, see the documentation at https://docs.github.com/en/free-pro-team@latest/github.

From the perspective of a beginner, the first approach would probably be off-putting as it assumes you already know what the terms ‘forking’ and ‘pull request’ means, so our beginner starts their journey by feeling stupid.

Approach two is an attempt to simplify the language by using roughly equivalent non-technical terms but it doesn’t explain how to copy the code and send the changes, and our plucky beginner will be no better off when they do eventually meet the terms ‘forking’ and ‘pull request’.

Approach three is more verbose, I admit, but it introduces all the terms, explains the process, and provides guidance if needed.

When is plain language too plain? #

This is where it gets tricky. Plain language is more accessible (for example to people with disabilities), but at the same time if you use language that’s too plain for your intended audience, then you risk appearing condescending. The key element is the for your intended audience part. One definition of plain language states that it is “Language that allows readers to make an informed decision about the content because it considers their literacy levels, cognitive abilities, contexts, wants, needs, attitudes and challenges” (Candice Burt, via https://en.wikipedia.org/wiki/Plain_language). In what seems to have been a well-received experiment, the journalism website ProPublica published some articles and editors notes on disability rights alongside their standard text (https://www.niemanlab.org/2020/11/propublica-experiments-with-ultra-accessible-plain-language-in-stories-about-disabilities/). Your reaction may vary when reading the plain language translation. Personally I wince at using “caring” or a derivative of it, 4 times in a 3-sentence paragraph, but I like the general sentiment.

However, the level of plain language used does need to take into account the expected audience. Sumana Harihareswara writes of mixed reactions to a FAQ on sunsetting Python 2 that was written in a plain language style. When I read that, elements of it do make me cringe, though partly that’s to do with the same issue of repeating words, but also starting sentences with “And”. I think it ought to be possible to write in plain language without doing either of those things.

Finally, I was recently introduced to Hemingwayapp, which does a good job of assessing the readability grade of your writing, and suggests appropriate changes. Not everyone uses a full-blown word-processing package so this is a useful service (and free). Writing for your audience, but also ensuring you don’t alienate or condescend, is a really fine balance to hit- and thinking about these two issues in depth has given me even more respect than I previously had for technical writers!