Skimmabilty in Technical Writing

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.