Hard as it may be to comprehend, a technical writer’s job isn’t to create content. It is to enable the user to complete a task through instruction. This doesn’t in any way imply more content. It is hard to get one’s head around it, but that really is the ask.
In this article, I will discuss some common errors in approach that technical writing teams make when they create documentation for a product. None of these errors are made with intent, it’s just muscle memory.
Documenting every field on a page
This one gets my goat every time I see it. How many times have we seen an article that tells us what we should fill in for First Name, Last Name, and many such common fields. Once is too many for me. When a user comes to the documentation, they are usually in a hurry to get something done, and that something is not reading the article. Now they have to sift through a whole bunch of definitions for common fields to get to that one field with which they want help. When they do get to it, it is usually some inane statement along the lines of the collection of garbage is called garbage collection. Don’t worry if you didn’t get the joke, it just means you never had to study C programming.
The only time you need to document a self-evident field is to remove ambiguity. This almost never happens. For instance, you’ll find the description for Serial No. as “The serial number of your device.” You look at the label stuck to your device and find three numbers that could all be candidates for serial number. The documentation will never clarify which one you need to enter in the field.
Why this happens: For completeness. Most writers are uncomfortable documenting just a few fields while leaving the others undocumented.
Describing water to fish
Often the software company you work for is a bunch of techies building a solution for somebody who uses technology to complete tasks in a world they don’t inhabit. For instance, engineers or computer science graduates building an accounting software. Accounting and the concepts of accounting are strange and new to the program managers, programmers, and, yes, the technical writers. So you catch them preaching to the choir, explaining double-entry accounting. Explaining what a BOGO discount is to a shopkeeper.
When you write an intro to the article, you must ask yourself whether you are describing water to fish. Your readers, most probably, find that brilliantly crafted intro tedious and a waste of time. They just want to know how to get it done.
Apart from intros, this happens mostly with field descriptions. When I see someone write a field description for Bank Name and Account Number, I want to laugh.
Why this happens: The PM describes the feature to the writer. A lot of time is spent in getting the writer to understand the concept. If the writer is someone who takes notes, most of the notes will be about the concept. Once they have understood the concept, the procedure is usually straightforward, and almost none of the notes will be about the procedure. Now when they go back to their desk and start writing. They spend a lot of words explaining the thing that was toughest for them and end up educating the fish about the water.
Documenting every variation of a procedure
This one is particularly difficult to identify because it sort of creeps up on you. Let me illustrate. Your software is built for supermarkets. Most people make payments using their cards, so your software supports a variety of card readers. When a client gets a card reader, they have to do two things – connect the device to your software, usually through a USB connection, and they have to connect the device to the internet to process the payment. When you started out, your software supported just one brand of card reader. Typically, the one used by your only customer. So you create an article that lists the steps to connect the device to the software, then to the internet, and finally how to use it.
But as your client list grows, the software begins to support more card readers. So as each type of card reader is added, you write a new article for that card reader. Every article will stand alone and complete. Makes total sense.
When you stop and think about it, the only part of the procedure that is unique to each card reader is how it connects to the internet. The rest of the procedure is the same for every variant of card reader. But now, you have the common steps repeated in 15 articles because your software support 15 different card readers.
While that makes sense at a unit level, think about how your users are going to look for the article. The highest probability is that they will search for “add a card reader”. Now they get 15 articles in the search results. Let’s approach this another way, shall we? Let’s call the article, “Add a card reader.” The article starts with how the user would connect the card reader to your software. This is followed by individual sections on how to connect each different card reader to the internet. Now when they search for “add a card reader”, they get one result and all the information they need on one page.
Another problem that this will definitely bring up is when the procedure in your product changes. Now you need to update all 15 articles.
Finally, the word count problem. You are saddled with a bloated document set. Ouch!
A technical writer must always know how the user is going to get to the article. If you don’t ask yourself that question, you will never see this coming.
Why this happens: Like the other problems discussed here, this comes from a good place. The writer just wants to document everything and doesn’t want the user jumping from one Help page to another.
Writing advertisements instead of procedures
Seeing adjectives in a technical document is a red flag. As technical writers, it is not our job to make subjective judgments about whether a feature has made life easier for a user. I am usually loathe to claim that some fix has improved a feature. The procedure is what it is and nothing more. The job of selling the feature lies with the Marketing team.
In my years as a technical writer, I have developed a healthy skepticism towards a PM’s claim on how cool and easy a feature is to use.
Another aspect of documenting improvements that makes me uncomfortable is that the new way of doing things quickly becomes the only way of doing things, but the documentation continues to call it the new way.
For instance, the product interface has changed, and all the action buttons have moved to a toolbar at the top, leaving only the Save and Cancel buttons at the bottom of the page. An article highlighting the changes is superfluous. Two months down the line, nobody is reading it. But it continues to be part of the document set. Highlighting the benefits of such a change as this one is Marketing’s job. The help documents should only update all procedures that are affected by the change to the new way of doing things.
Why this happens: This is usually the result of an overzealous writer getting carried away by the descriptions of the PM. The only way to avoid it is by being aware that it is happening.
Creating FAQs
FAQs are a great band aid when the documentation has missed some aspect of a feature that the users are looking for. But FAQs are like work and children, they grow to take up all available space.
If you have FAQs in your document set, you should also consider setting up an audit cadence to identify what needs to go into the regular documentation – sometimes as a complete article and most times as a note in an existing document. The audit also helps clean up instructions that are no longer valid. I have seen too many FAQs where one Q directly contradicts another.
Moreover, nobody really types questions into a Search box. Most users search using keywords. So it is not necessary to frame your articles as answers to questions. Doing so actually limits the article.
Why this happens: This is the direct outcome of trying to reduce support tickets through documentation. A laudable goal, but one that can be achieved through better documentation methods rather than FAQs.
The internet is full of articles on what errors a writer should avoid when writing documentation. However, I couldn’t find anything that discussed the mistakes made by teams in terms of their approach to documentation. That is why I wrote this up. This is in no way a comprehensive list but just the tip of the iceberg. Do feel free to add more items in the comments.
Commenti