Image for post
Image for post

Blank sheet. Reader clearly defined. Knows nothing about what I’m going to write. Is ready to stop the moment I say something that she —no, he — cannot understand.

My goal is to start with something familiar. Like sports. Then to go a bit deeper, to sing, he and I, reader and writer. And then to introduce a third person. When it all ends, she’ll be in bed while he continues to play some stupid game that has something to do with lifting things.

If that interests you, please read on.

Every game has rules. Otherwise, how do you play? Imagine a game with no rules. You pick up an object from the street, anything. Another person does the same. What’s the game? Whoever drops it first, wins. Or whichever object is bigger, or heavier, wins. …


It’s hard to know where our professional persona ends and the rest of our bodies and minds (and souls, I guess) reside.

This presupposes that there is indeed a difference between who you are professionally and non-professionally.

In my case, this presupposition feels true on almost every level of my being.

For example, in my role as technical writer, I am constantly challenging my investment as a writer. I write and read all of the time — at work, at home, not at home not at work. Mostly fiction. Journaling all of the time.

So where does technical writing fit into this otherwise literary world? Here: somewhere between clarity and ambiguity. …


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. …


Image for post
Image for post

This is the last in a series of articles in which I express frustration with the art of technical writing. This series came about while undertaking a particularly difficult assignment for my company. Writer’s block can be selective — it was far easier to blog than to do my assignment. But it’s thanks to blogging that I finally faced the beastly assignment.

Our day jobs are punctuated with the purely executory, like filling out papers and filing folders, or performing hundreds of simple hand / eye movements to complete a daily or weekly chore.

Some jobs are only this, and I am thankful that this is not my case, as technical writer. However, as technical writer, I am hounded by the mundane and repetitive task. I avoid thinking about the number of times I’ve renamed files and folders, redirected URLs, cleaned up code, added or deprecated parameters, shortened already short half-sentences, and searched and replaced one boring technical term with another. …


For some technical writers, writing a blog comes as a relief, a sudden respite from the exigencies of precision and concision. Like when a tour guide goes off alone onto the less-trodden paths of her homeland, plunging deeply into familiar digressions of ambiguity, subjectivity, and multiple levels of meaning. Technical writers can digress too. In a blog.

The success of a blog lies not in its content but in what it provokes, because while everything on the surface is content, nothing being said is on the surface.

Thus freed from helping others to understand precise technical terms or do something correctly, a blog attempts to help people think differently and to engage them to say not only Yes or No but Maybe. Writing a blog can move a reader from one vague point to another, because life is the stuff we place in suspension between two edges. …


When I am asked to define my role, I start with “Technical Writers write Technical Documentation”. But to be honest, the word in the middle is incorrect: there’s a difference between writing and documenting.

For example:

  • We document API methods and parameters, filling pages with code, syntax, and expected data formats and types. Facts.
  • We write technical guides, making difficult concepts easily understood, help users follow best practices, enlighten.

The difference is therefore pretty straightforward.

To Document

API documentation requires as little wording (i.e., writing) as possible. It is thorough, precise, a source of truth. Mistakes are intolerable.

The pages of good API documentation should contain mostly code and one-word descriptions like “boolean” or “optional”. The key ingredient is useful: they should be immediately useful and not get anyone to think. Tell not show, and definitely not entertain. They should get people up and running, fast. …


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. …


Image for post
Image for post
That’s me traveling in the documentation space

Awe. Like I am part of something insanely large. Touching infinity.

We travel in space. We are in space, and we and everything in it are moving.

To see this, get out of the city and into the dark country. Lay back on the ground and face the sky.

It takes about 30 minutes for your eyes to adapt.

And then feel the movement.

This is what happens after a few days at Algolia. You take a step back, and you see something rare, extraordinary — an insanely large and infinite potential.

The stars are within reach. They are in the open space, and in the super quiet, with genuine conversation in the hallways, kitchen, and on the couches. …


Writing only needs two dimensions

Image for post
Image for post
Software / API documentation is geometry

Software documentation is about building software, and building involves geometry.

For example, when you look at some common criticisms of documentation —

  1. “The text is not clear!”
  2. “Information is missing!”
  3. “The content is disjointed! No matter how much I read, I just don’t get it.”

— you’ll see how thinking geometrically can solve these problems.

For the first two criticisms, you need only simple lines and squares. The third requires triangles and a bit more math.

Writing horizontally — the sentence

There is a horizontal component to writing an English text — horizontal in a purely left-to-right direction: the sentence.

We balance everything on that horizontal line. We leverage clarity, readability, and style. Spelling and grammar require zero height. For a line to remain single-dimensional, it must be concise, accurate, understandable, and unambiguous. …

About

Peter Villani

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

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