The Process of Technical Writing

I think I’ve been doing what I would call technical writing for most of my life. So far as I was concerned, every time I put my mind to writing an instruction, a correction, a training manual, a policy or procedure, or even a simple report, I was undertaking technical writing.

Technical writing is the communication of ideas in a logical, connected sequence at the end of which the reader has understood something new. I tend to regard it as a format rather than a style: a container into which things can be put so that they can be retrieved at will, consulted and understood.

Forty years ago I didn’t know that what I was doing was technical writing. It was just a means of passing on information, ideas, instructions and, sometimes, just news in the workplace. Consequently, having finally discovered that what I was doing had a name, and having accepted that name, I was a little miffed to find that the meaning had passed on and had limited itself to people who wrote software instructions in the IT world. Heigh ho – I still think Technical Writing has a wider definition.

Speaking of IT Technical Writing, I have read many of those instructions and – I hope Microsoft’s writers are reading this – I think the teaching work they produced was often horribly deficient. Even as references the texts were reliant on outside knowledge. I found an object lesson there.

Two of the things I learned as a teacher helped me define what was wrong with the technical writing in the IT textbooks I struggled with. The first thing that I came to understand was that technical writers felt that if they explained themselves clearly, logically, and once, that their readers would immediately understand what they were talking about. It’s a common mindset, but wrong. The writers failed to acknowledge that every mind is different. Each individual brings a unique set of experiences, memories, skills, and methods of understanding to bear on their learning process. Presenting an individual with a monolithic set of instructions based n a shared technical knowledge simply ignores the certainty that a solid percentage of those reading the instructions will read them imperfectly and not have the assumed level of knowledge to understand them completely. If you understood the manual, you didn’t need it.

The second teacher’s thing I learned was that the key to teaching information was not to direct your efforts towards creating an understanding of what you are trying to teach: but to direct your efforts to seeing the misunderstandings inherent in your lessons. You can teach best once you have worked out how people will misunderstand what you say. You cannot rely on the assumption that all knowledge and skills are commonly-held by your students: your students are not in your mind and you are not in theirs, however skilfully you think you might be teaching.

So good technical writing comes to rest upon the fact that clear communication is only the first step. Beyond it comes the acknowledgement of personal differences of acquired knowledge, attitudes and expectations: and the active seeking out of those differences so that the holes in the container can be plugged.

You’ll see how in my own definition of technical writing relies less upon the words and more upon the ability of the technical writer to anticipate what is not in the mind of the reader and to provide ways of filling up the deficit: hence my metaphor of the container from which things can be taken as needed.

Editing, language and writing