Allen Baird PhD
The best scenario for us as technical writers is if we can get in at the very start of a new product or project. Then, we can make sure that things are done properly from the outset – for example, style guides, tone of voice, naming conventions templates, processes, and task management.
But, often, we’re called in to take over the technical writing from inexperienced writers and other contributors who’ve been doing the best they can, even though they’ve no knowledge of technical writing approaches and techniques, and have no time to ensure a consistent style, structure or standards. Here is a list of mistakes made by these reluctant writers and how we solve the problems they unwittingly create.
Mistake #1: Working from document to document, without any overall guide or standard to ensure consistency
Consistency within and between documents or topics is one of the principal hallmarks of quality technical writing. It demonstrates a basic level of professionalism in any type of support docs and resources. But, more importantly, it relieves the reader of any agitation caused by having to relearn now to interpret and apply each similar written procedure, table or explanation for a product. They know exactly what to expect every time they open another document for that product.
This is where a Writing Style Guide comes in. Writing such a guide is one of the most important pieces of groundwork we carry out when starting a new technical writing project. This guide contains all pertinent information on writing standards, naming conventions, tone of voice, style and structure, templates and formatting, grammar foibles, and how to structure and write specific types of content. It’s something that grows with the project, helps orient new contributors, and acts as a decision maker when opinions and styles differ.
Mistake #2: Lacking explicit procedures for who does what, when, and for who
This is a similar problem to Mistake #1 only it has to do with the writing process for documents rather than their standards. A Content Procedures document solves this problem. It spells out the documentation request, creation, writing, editing, reviewing, permission and publishing processes for different sorts of technical document. There may be different steps for different products.
And once a document has been published, everyone involved needs to know how it is updated, republished, and archived. This is vital because technical documents are living, dynamic documents that are subject to continual updates, all of which must be recorded and may also need replicated across changelogs, project management tasks, release notes and blog posts.
Mistake #3: Assuming too much technical knowledge on the part of users and readers
Technical writing is the place where the technical aspect meets the communication aspect of a product. Often, the technical experts and developers who work on the product are given the responsibility to write about it. While it’s necessary to have their input, it isn’t sufficient. Technical documents written solely by developers tend to be poorly structured, filled with jargon and full of assumptions about the audience.
In this case, technical writers need to work with developers to translate the language into a form that users can easily follow. They also need to glean from the developer information about the context of the topic or procedure, why it is important, what it can help developers or users achieve, how basic terms are defined, and when it would be used. This helps the technical writer to produce an introduction and explanations beyond the basic steps.
Mistake #4: Writing support documents as if they were technical reviews or blog posts
This is a recurring problem with team members who are really passionate about their product and possess a detailed knowledge of it. Maybe they have experience of writing about related issues for online websites or magazines. They have a lot to say about the product and end up writing pages that are so technical they are of minimal use to the intended audience, at least not without a heavy application of structure and translation of the jargon.
If the solution to Mistake #3 is to bulk up, the solution to Mistake #4 is to slash down, rigorously and ruthlessly. It may be that that some of the content can be converted into a step by step guide, a table, or even reused later for a blog post or white paper. But, for the most part, those who use technical documentation want it to tell them how to do something. Without basic explanations and procedures, it is useless. And any information that detracts from these basic requirements is also useless without rewriting. Succinctness is a crucial technique for a technical writer.
Mistake #5: Having support documentation scattered in multiple places and formats
When a new piece of software, platform or plugin is put on the market, support documentation is often hurried and reactive. Users will ask questions and point out problems. The development team quickly throws together and throws out responses on a point-by-point basis. These might take the form of an embryonic support page, but answers to customer FAQs are often found in blog posts, PDFs, random longer guides, Q&As and many other types of content.
Our task here is to map out the state of all support materials as they currently exist, usually in a spreadsheet, initially. All details of each source of information – name, category, URL, subheadings, date of publishing – are captured. We then make a plan for a new structure into which this lot, and all the missing information, can be added. We call this process ‘information architecture’. It helps lay the foundation for all future topic development.
Mistake #6: Leaving large gaps in support documentation because the software or UI is ‘intuitive’
Intuitive… in whose eyes? To those who have developed or who sell the product? To those who are already familiar with the specific product? To those who are already familiar with this family or type of product? To those who already familiar with the industry?
Intuitive or user-friendly software often relies on pop-ups, tooltips and other context-sensitive help to add simple definitions and explanations to the UI. They need written properly too! We’ve often come across documentation where the information in these pop-ups is poorly written and even seems to contradict information to be found elsewhere. The audience must be considered in every piece of technical writing content, from names of dialog boxes and small pieces of text to longer installation procedures and API documentation.
Mistake #7: Lack of information on the history, assignee and current status of a document.
We’ve landed in situations where there is a document written but no one knows what stage it’s at, who worked on it last, what changes need made to it and whose job it is to make them. Yes, there are comments in the document, and it has a history to view. But that is not enough to prevent the creation of multiple versions of the same document by accident, or for the document to be forgotten about due to other priorities.
We create a card in a task management system for each document. We add a link to the document and give the task a meaningful name, an assignee, a date, a state, a priority and a description. The task follows the document throughout its lifecycle. An update is added to that task every time the document is updated. This means all contributors and viewers know where to go for the definitive document version and what stage it has reached. Everything is transparent and coordinated.
If any of my readers are also technical writers and can think of other common mistakes you encounter, we’d love to hear your take on them and how you dealt with them.
Photo by Varvara Grabova on Unsplash