Skimmabilty in Technical Writing

Peter Villani
Jan 20, 2019 · 3 min read
Image for post
Image for post

While rethinking my company’s technical documentation, deciding on how to improve the developer experience, I had a revelation. I suddenly knew what developers needed from technical documentation.

I know that revelations are not always true. In fact, they are sometimes so wrong that they are dangerous, making us believe we are in the presence of truth, getting us to act, take decisions, without encouraging us to put into question whether the force of the revelation is stronger than its truth.

At most, “revelatory truth” is a circuit breaker. It is a sudden electrical force that lights up an entire sky and then explodes, burning away the dark, uncomfortable matter of confusion and unknowing.

Our bodies are deeply uncomfortable with not knowing, so we need a release, and revelation gives us just that — It gets us to exclaim: I’ve got it! Now I know! We feel freed and enlightened.

But turning a bright light onto a dark shadow only makes the shadow disappear, the object still exists, and it still needs to be discovered and examined.

But anyway, What was this revelation? And did it hold any grain of truth?

Here it is, in all its truth and falseness: Developers don’t read. They skim.

At its worse, this revelation tells me that developers rely on an advanced form of skimming called scrolling, which they do at lightning speed until they find code, which they then copy, paste, and compile, and then spend the rest of their time resolving runtime errors — all this as opposed to, say, reading.

Developers don’t read. Did I already say that? As a technical writer, I am forced to ask: What are my words producing? The answer: Thicket.

I am not writing, I am creating thicket. Words, sentences, long paragraphs, pages of content — in a “word”, all non-code-content is essentially thicket to be bushwhacked to reach code.

Thicket or perfect text, it’s all the same: verbiage in the way of doing.

By the way, the revelation didn’t say “the less said, the better”. I’ve already had that one, and that wasn’t easy to digest either— What kind of writer likes to write less? But this one’s more existential — Don’t write. What kind of writer does not want to write? And yet in the perfect developer world, code + a few choice words should be sufficient.

The revelation is that I need to create skimmable content. Skimmable is not even a word. But it’s easier to understand a single non-word like skimmable than to read 10 words like “content that one can understand on the spot without reading”.

Well, the revelation does indeed ring true, and as I sort of rant about it, I convince myself of its truth — and then I nonetheless go back to work creating short, single-idea sentences, simple, short paragraphs, useful, short pages, and no code at all, but with clear links to pages with loads of code and examples, thus striking a compromise that satisfies my technical and increasingly non-technical readers who most definitely read, because many of them are not there to code but to understand, analyze, use (not code), decide, manage, buy, and/or understand what their developers are doing. (Still reading? That run-on just kinda slipped out.)

And then I get the job done, wait for feedback, and its mostly positive, even from the developers who appreciated that I had taken the time to explain the concepts behind the code.

Writer’s Blogk

Peter Villani

Written by

Started writing this blog to reflect on my technical writing craft. I have another blog where I reflect on everything else. www.codeharmonics.com.

Writer’s Blogk

Notes from the technical writing underground. Journaling by a technical writer.

Peter Villani

Written by

Started writing this blog to reflect on my technical writing craft. I have another blog where I reflect on everything else. www.codeharmonics.com.

Writer’s Blogk

Notes from the technical writing underground. Journaling by a technical writer.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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