Technical Documentation for the Hurried Polyamorous

Peter Villani
Feb 17, 2019 · 2 min read
Image for post
Image for post

People who come to read technical documentation are rare indeed. Most come with an urgent need to be guided, to be taken to where they need to go. On their way, they want to see as little noise (words) as possible. They are only happy when they see words like Exit, Pull, and Push — especially on doors obviously used for exiting which can be either pulled or pushed.

The learner-by-doing is looking for how to set something up, and where to put his or her code, and how to run it, and what kind of data to use, and why this error appears, and so on.

And who needs more than that? It’s love at first sight, so fast and blinding that he and she and he and he and she and they actually see nothing, not even each other, as they do only what they desire.

People are not coming to your words to read, but to use them as a tool. To turn a screw, open a car door, lift a hot liquid in small mouthfuls, and sneak a lick of chocolate at the bottom of the mixing bowl, a stolen pleasure savored in the moment before the next comes along.

This is what functional text should do: get people to do something with as little blocking the path to doing. Make it easy for people to take out their ruler, do a few measurements, and then screw or hammer away.

It’s that visceral.

I hate shopping malls. So I can’t think of a better experience than to be guided directly into a store, to a shelf, to the item, and then directly to the register, out the store, out the mall. Pure guidance. No time to think. No bothering with the noise of the winding halls of crowds and massive department stores. In and out in no time.

That’s what I like.

A document that tells me how to do something is far more exciting than one that tells me what I am doing and why. Leave that up to me. That’s my thang. I just want to do. Give me the fix and the means to do it. Give me the installation, the data, the code. Give me pictures, the menu, and where to click my mouse. I want it to be tactile, immediate. I want to feel the sensation of completion. Done. Let me move on to another.

Give me technical content that appeals to the hurried polyamorous.

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