Idiosyncrasies of the Effective Technical Writer
Technical Writing, having now evolved into the broader realm of ‘Technical Communication’, has always been an interdisciplinary, eclectic enterprise that employs an adventurous spirit and often calls for combinations of seemingly incompatible skills and interests.
In the magical world of computers and more specifically in the computer software industry, a technical writer (also known as technical author, documentarian, documentation developer, documentation specialist, technical communicator, and more) is the nosy fella in the team who never stops bothering programmers with questions and who would do what programmers normally hate doing – write something that is not code. Write documentation.
Tech writers explain to computer program users how those computer programs work.
These end users are our ‘target audience’ – ranging from humans with no specific technical knowledge, to very technical staff such as developers and professional services in the same or partner software groups. Consequently, the produced ‘documentation’ can range from high-level user guides written in a language style suitable for a 5th grade school kid (or perhaps that was in the past as 5th grade school kids nowadays might be more technically advanced than their elders), to developer guides that explain code to other programmers.
Ask a tech writer “Why/How did you become a tech writer?” and I bet you’ll hear something along the lines of “eh hm well I had never intended to become a technical writer but then it happened so that …”. I’ve heard that many times and I know of excellent tech writers who originally started as computer programmers, scientists, linguists, journalists, translators, even teachers. I also know tech writers who then became QA engineers, computer programmers, and creative writers.
It is considered that the first ever document written solely for the purpose of providing computer-related user-facing instructions was the user manual that Joseph Chapline produced in 1949 for the BINAC computer.
This gradually became a taught-of discipline and the first specific technical writers adverts started to appear in the ’50s. The renowned Society for Technical Communication was founded out of the merging of two New England based professional technical writing associations.
In the ’60s, the rise of computer and aeronautics technologies saw more and more job openings for technical writers who could provide readers with informative and readable documentation and instructions of use for the machines and processes being developed.
Despite the gradual rise of technical writing jobs and technical communication journals in the’70s, technical writing was only legally recognised as a profession in 1980.
The first desktop computer-based technical manuals were published in 1987 using the Corel Ventura Publisher and Adobe FrameMaker tools for documentation development.
The ’90s saw the introduction of ISO 9000 certifications and XML, which, needless to mention, led to an overhaul of the way technical documentation was developed.
More recently technical writing evolved into technical communication, mainly due to the expanding set of available media outputs and communication channels (e.g. video embedding and streaming), as well as the introduction of social media as a means of real-time communication.
“Make ‘em read” – it is all about building a critical level of confidence with your potential readers that they would be able to find the information they need at the right time, in a timely manner, with easy access, and with good quality. Ultimately, if your documents are useful enough and well written, your readers will come back for more.
"Proper" software technical documentation is supposed to be:
Fun to read, or at least not too boring
This all sounds great and pretty obvious but in reality it’s not that easy to achieve. If you were a tech writer, here are some of the most commonly observed problems that you might face:
Strong technically but an unconvincing writer. You are a tech guru but you cannot write well. It could be that your language skills are not adequate; or that you are not a skilled story teller; or that your "instructional" skills are lacking in depth; or that you are not capable of conveying your intended meanings easily; or that you struggle when you attempt to explain complex technical concepts in a primitive style suitable for humans; and so on and so forth. The result would be documentation that is technically correct and complete but so hard to read that it would be practically unusable.
Strong writing skills but technically incompetent. You write well and you are a good story-teller. What you write is enjoyable and amusing to read. But you don’t know well enough the technology and/or software you write about. The result would be documentation that is technically incorrect, incomplete, and/or inconsistent so it would be of no use to your intended audience no matter how skilled a write you have produced. After all, the main purpose of software documentation is to instruct its readers on how to use that software correctly and efficiently.
You skip information that you consider too obvious to document. Wrong (usually). A technical document is supposed to include the “complete” details, no matter how intuitive an app UI is or how obvious certain user actions might seem to most users. I may have heard of complaints about installation guides and why we needed to go through all those wizard screens in detail – well the truth is, 99% of your readers will not need this reference but there might be that 1% who would, and that’s where our responsibility as tech writers lies. We are there to instruct and coach our users, but also to inform “on demand” when necessary, and the latter means that “all” of the relevant information must be in place.
Your style is inconsistent or inappropriate. Documents have to be attractive to readers but this doesn’t mean that you can employ a style that is too colloquial or one that might sound inappropriate for certain audiences.
Developers won’t cooperate with you. It might be that someone from Dev is always too busy and not willing to spend any time for such a petty, low-priority thing as documentation. This is still very common for a lot of developers and even entire teams, and it's one of the main reasons there are technical writers in the first place. It is your call to break the ice and find a communication channel that works with such programmers. You can try buying them beers/pizza too, if nothing else helps:-)
The list can go on and on. To successfully face such challenges, you need to retrieve and compile…:
These are the four amazing powers of observation that make a tech writer an effective one:
Be technical. Never ever get tired of learning, reading, and asking stupid questions.
The more technical knowledge you have, the better you will understand what you need to describe in your documentation. It is a must for you as a tech writer to quickly become a major domain expert in at least one of the major technical fields of expertise relating to the software you document. Obviously you could not document a piece of software if you didn't know everything about how it worked and was intended to be used.
In addition, a tech writer would quite often walk in the shoes of a tester. It is because when you document, you naturally test what you write about – whether it be a task procedure or a description of a concept or a term. It could also happen that tech writers share the same time frame with testers during the QA cycles in a sprint (or during the QA cycle prior to a release).
So if your docs are:
incorrect (technical correctness), or
incomplete (consistency), or
… then you need to improve your knowledge about the software you’re documenting and your relevant domain knowledge.
Risk fact/or: Know and respect your audience. No matter how technical you become and how absorbed in a new technology you might be, never forget to observe the correct style and level of technicality that is suitable for the target audiences of the documentation you produce. I’ve seen tech writers become so enthusiastic about how technical they are in a certain field that they sometimes fail to write in a readable, concise, and attractive documentation style that complies with the needs and expectations of their target readers. Instead, they’ve ended up providing too much technical details for the wrong reasons and in the wrong places and documents; as a result their documents have become difficult to read and even more difficult to understand by certain reader types – because they are out of scope.
Know how to write concisely, informatively, and in good style.
A background in linguistics, language, expression, style, translation, philology – it all helps. It is not an easy task to transform a piece of knowledge from one brain to another one, and it is even more difficult to transform information between whole groups of people.
If your docs are:
not useful enough (usability), or
difficult to read (readability), or
badly structured / formatted (layout), or
unattractive and/or boring to read,
… then consider changing your writing style and techniques.
Risk fact/or: Observe a neat technical communication writing style. There are lots of good references (e.g. the IBM Style Guide , the Chicago Manual of Style, the Microsoft Manual of Style, and more).
Communicate, listen, interview, translate, emphasise, empathise, get feedback.
It all comes down to one thing – you want to make your readers read the docs, and – oddly enough - you can only succeed in this if you are able to be a good listener.
One of the main (and most time-consuming) daily routines of a technical writer is the “info hunt” raid - i.e. asking developers and other team members for “interviews” and demos so that you can gather your information about the product feature you are documenting, and understand how it all works. So, ask your questions (sometimes stupid ones), and generally be nosy about Anything related to the object of your documentation.
It is part of the communication process too, alongside product management, to make your documentation available to the intended readers and to advertise it in the available channels and ways.
So if your docs are:
incorrect (technical correctness), or
incomplete and/or badly presented (consistency), or
not useful enough (usability), or
difficult to read (readability), or
difficult to find (availability), or
difficult to reach (accessibility), or
badly structured and formatted (layout), or
unattractive and/or boring to read,
… then you should work on your communication skills and improve your communication channels with your subject matter experts.
Risk fact/or: Build solid work relationships with your subject matter experts. Failure to do so usually effects in delays in the feed of information that you need for your documentation, as well as during the review and QA phases.
This is what I’d call “the creative bit” - the glue that sticks it all together. This is the extra bit of communication that can help you to effectively translate information coming from a certain mindset (say, a programmer’s way of thinking) into information that is for the eyes and ears of a totally different audience (for example, a sales person, a graphics designer, a bank official).
This is what I meant, at the start of this article, by claiming that being a technical writer was an eclectic, interdisciplinary enterprise. A good tech writer is able to understand and to mould various lines and layers of human perception in order to “hear” their audience and to anticipate and meet their documentation needs.
It is just like with creative writing - it is not just enough to know much about human behaviour and to be capable of describing it with words: you need something extra and that extra bit is the charisma, the magic that you would put into your words, your writing, your music, your art, your scientific reasoning, your computer documentation, anything you do.
As for me, my major inspirational baseline was music and its inherent bonds with mathematics and consequently with computer programming and logic. Since my early childhood years, mathematics and music have always been twins of the same descent to me – just different faces to the same holistic knowledge that embodies all that the human mind is given to indulge in. The first time such a parallel struck me was when as a kid I came by a book claiming to be Ray Charles’ autobiography. In that book, Ray Charles had shared that solving mathematical problems and unravelling musical puzzles was to him naturally the same thing - the same mind routine. My assurance of this fact was all the more reinforced when in high school my class took part in an experimental year of studies of Pythagoras’s mathematics that also dealt with the connection between maths and music.
Here’s a handful of further examples that have proved personally inspirational for me when it came to connecting the worlds of technical writing, music, maths, computer programming, and creative writing:
Tord Gustavsen. One of the most innovative modern jazz musicians and composers, Tord Gustavsen also has a PhD in Philosophy. In one of his essays he draws some parallels between five basic dialectical dilemmas (moment vs. duration, difference vs. sameness, gratification vs. frustration, stability vs. stimulation, and closeness vs. distance), and how the process of jazz improvisation influences the author/musician and his/her interaction with the audience and environment: “The improviser relating to, making sense of, acting on, and being formed by his or her musical surroundings, that is, the sounding music, by the physical instrument, and by the fellow musicians (if any).” If we were to translate this into the technical writing domain, a similar multi-channel, multi-layered interactive pattern can be outlined. In a similar way, a tech writer should listen to their audience (target readers via feedback channels, as well as predictive analysis of target reader groups) and to the voices in this environment (subject matter experts). At the same time, just like a pianist should deal with the hardware specifics of the piano as an instrument, a tech writer is restricted to, and helped by, the technology and hardware/software they use. A jazz improviser can either own the stage and enchant their audience, or bore them to the point of losing interest in what is going on; similarly, a tech writer can either present the technical information in an attractive, useful, readable way, or produce a mountain of words that do not form a coherent piece of writing and are hard to read and understand. The key to success in both cases is the ability to lead, listen, and adapt – all at the same (real) time.
Jan Garbarek. A prominent Norwegian jazz saxophonist and composer. His original music pieces are known for the extreme minimalism they employ – complex musical landscapes and emotive progressions are expressed by means of chords and movements using just 3 or 4 tones at a time. Although this example is a bit extreme, I would always value a concise writing style in technical documentation using the right words in a minimalistic way to convey as much information as possible.
Joseph Chapline. As already mentioned, he is deemed as “the first technical writer” in history. But a short time after that he turned to music and became a professional musician. I couldn’t explain that better than it’s already noted in the provided link: “Perhaps this story has something to tell us about the possibilities of technical writing, maybe not. Perhaps the brain that’s suited to music is also suited to creating complicated documents. After all, isn’t a musical score an assemblage of notes in the right order so that anyone can play them, just as a user manual is a compilation of instructions so anyone can use them?”
Ernest Hemingway. We all know why, don’t we?:-) Perhaps the most spot-on description of what the ideal (technical) writing style should be: “If I started to write elaborately, or like someone introducing or presenting something, I found that I could cut that scrollwork or ornament out and throw it away and start with the first true simple declarative sentence I had written.”
Ray Charles. See above.
Darth Vader. I find your lack of faith in documentation disturbing!