A common complaint I hear from technical writers is that we are not taken seriously in the organization. There are, of course, many reasons for this, but the fact remains that the success of a product should not depend on documentation. When you hear product managers and sales teams complain about documentation, nine times out of ten, it means the product is so badly built that it is unusable without documentation. Documentation is the band-aid holding a bad product together.
Does that mean that documentation teams should resign itself to being second-class citizens? Far from it. For too long, we have considered our role to be to document procedures. Instead, our role is to be advocates for the end user. We must focus on the forest and not the trees.
Our trees
Consistency: I know that it is controversial to have consistency on this list. It is not my intention to downplay its importance. Let me explain with an example. Consider a service request form shown here. There are four feilds, but only one that requires explanation. Most TW teams will balk at defining only the Serial No. field. It is contrary to their definition of consistency. But does telling the user that they must put their first name in the First name feild add any value? I contest that we should be consistent about not documenting obvious stuff.
Grammar: Another controversial topic. Yes, it is important to write in grammatically correct English. But is that our job description? Or is our job to help the user complete the task at hand? If we can do the latter in good grammar, fantastic! But no amount of good grammar will save incomplete or bad documentation.
Style: Often we elevate style guides to the level of style commandments. A guideline is meant more as a suggestion than a law. But a lot of technical writing teams get so hung up on them that these good-to-have guidelines become hurdles to jump over instead of smoothening the process of communicating key aspects about the product or process. When faced between adhering to a guideline versus clarity for the user, we should always tend to the latter.
Unimportant metrics: A pet peeve of mine ever since I got into the field has been the focus around pageviews. Whoever thought that pageviews is a good metric to track from the perspective of more pageviews means good documentation was just plain lazy. If you stop and think about it, the best way to get more pageviews is to build a crappy product. More pageviews just means the UX team needs to work harder. It has nothing to do with the quality of documentation. There are many such useless metrics I see documentation teams tracking. No of grammar errors by writer is another such metric. At best, it is a reflection on the recruitment process. If you hired a writer, there is an implicit understand that the person knows how to write in English. This metric gives us no information on whether the documentation is useful. Identifying and tracking the right metrics takes time, effort and thought.
My being critical of these aspects doesn't in anyways indicate that I think they are of no use. My issue is with the undue importance we attach to things that have almost no bearing on our primary task - to help users. This is why we are an afterthought in the development process.
The forest
As user experience began to take center stage in the success of a product, we missed the opportunity to get on that bus. As technical writers, we were (and still are) best placed to write UX text. But unlike documenting procedures, UX writing requires us to be proactive in our understanding of not just the product but of the vertical and the user. Instead, we chose to take the back seat. When people sent us screens to check, we did little more than a grammar and spelling check. We would get hung up on things like active voice versus passive voice. We’d throw tantrums about capitalization. This has, understandably, led to PMs and designers being frustrated with us and asking for specialist UX writers.
In an alternate universe, we would have looked at the user journey. We would have traced the steps a user would take and asked ourselves the question – What does my user need to know to be able to complete this step?
Going back to the example of documenting the service request form, if we arrive at the consensus to document only fields where users need help, then it is a small step to move that information onto the page itself.
How many times have you come to a decision point when setting up a product and wondered about the implications of choosing one option over the other? Once again, that information will be missing, or it will be buried away somewhere in the documentation. If we work with the designer at the time when they are designing the screen and focus on the user journey, it is not difficult to find a way to inform the user about the implications of their choice. There is no need to send the user out to the documentation to figure it out for themselves. Even if it means putting a clunky message box when the user makes the selection, that is better than directing them to the documentation.
We have no one to blame but ourselves for finding ourselves where we are. But it is not too late yet. To remain relevant, as we face the existential crisis that GenAI has thrown at us, we must move upstream and be part of the product development process where we can be the advocates for our users, which is our primary role.
Let me conclude with a recent experience I had with documentation. We recently changed the lock on our door. We went in for one of these fancy locks that allow you to unlock using a PIN, fingerprint, and RFID card apart from the traditional key. The lock comes with an app - doesn't everything? Setting up the PIN and fingerprint were straightforward. But I when I tried to set up the RFID card, it kept giving me some spoken instruction through a speaker embedded in the lock. Try as I might, I was unable to decipher what the Indian woman with a fake American accent was saying. So I went into the documentation. There I found the extremely useful instruction - Touch the card to the door and follow the spoken instructions. This is why everyone hates technical writers.
Comments