When a woman walks up to us and introduces herself as a writer, what are the most obvious conclusions to draw?
She could be a novelist penning thrillers or romances. She could be a poet or even be associated with cinema as a lyricist or story/screenplay writer. She could be a biographer for popular and not so popular personalities. Then you give her a second look and note the way she is dressed. If she has the grungy look about her, she could be a journalist scouting for a live story, or film/food critic. But if she is wearing the ubiquitous ID card of a hot-shot IT company around her neck, you are wondering who she is! Well, she is what you would call a technical writer.
Technical writers are a mixed species – they are basically writers. That means they can write in a way that educates and interests a reader. But they are also technical people. More technical the product, more technical the writing becomes. They need to be technical enough to uncover, understand a product and explain to a new user how it is to be used. Confusing, huh!
There are several myths and misconceptions surrounding the world of technical writing. This article attempts to dispel some of those.
While the first few forms of writing that crossed our minds at the start of the article are considered rather glamorous and creative vocations, technical writing does not immediately inspire that sense of admiration or recognition. But that is simply because technical writing is not a stand-alone vocation. It is meant to be part of a larger product development process. Most electrical appliances, electronic equipment, and computer gadgets fit the bill when we talk of products in this context.
Let’s look into some common instances. When you are to use an electric shaver for the first time, you might peep into the instruction manual before starting off. At least to figure out how long to charge the gadget for the first time, or to check if it can be used both wet and dry.
Moving on to a more multi-functional equipment like a broadband modem. First you need to figure out how to setup it up, unboxing as it is called in today’s gizmo world. Only then can the modem be put to use – for connecting to the internet, wired or wireless. So that leaves us with two documents – one installation guide and a user manual. Advanced electronic/telecom equipment such as a BTS for 3G network setup come in with even more documentation such as product configuration specifications, troubleshooting guide, training manual for operators and so on.
So, technical writing is not “just writing a user manual”. It could involve several documents, each aiding a specific phase of product usage – installation, normal usage, troubleshooting, maintenance, upgrades and finally replacement.
The product development life cycle typically consists of product ideation, requirement collection, design and development, testing, installation and deployment, maintenance. Then, the cycle re-enters ideation, for a new version and life goes on. So where does technical writing figure in this cycle?
Just like developers and testers, even technical writers receive the product requirements as an input document, right at the start of the lifecycle. So when the actual product is being designed, its information architecture is also finalized. Generally, the System Engineer in charge of entire product architecture and design is also responsible for test architecture and information architecture. Throughout the product lifecycle the hardware / software development teams, test teams and information development teams work in parallel.
Technical writers are also proxy testers. Once the product is ready for release, they follow the given requirement list and perform each user operation, to validate whether the actual functioning of the product matches the stated requirement. Only then do they document how each of these operations are to be performed. So the technical writing team is as much part of the product development process as other teams. Their contribution is by no means insignificant.
Unfortunately, most product releases in companies are a race to the finish as the formal release date approaches. Major version releases span a few months and hence technical documentation might be given ample time post development. But minor version releases mostly get just a few days to a couple of weeks to finish the entire cycle. So as soon as the requirement is implemented in hardware/software, the release is expected to be made, with just a short test cycle. In such urgent releases, technical documentation is often given a miss.
But there is a major risk in ignoring documentation updates. As time progresses, the documentation will not remain in sync with the product feature, as changes are not incorporated in them. Impact analysis of modifications on overall system behavior is supposed to be a key part of the technical documentation. When this is skipped, the end user may face system behavior which he is not expecting. This may lead to severe repercussions in complex products. You might be surprised to see the number for defects reported during final system acceptance phase by end users, that relate to inconsistency between feature implementation and documentation.
Technical documentation is an integral part of a product release. It needs to be given the same importance as development and test activities.
Gone are the days when English speaking countries in the western worlds were the key market for most electrical/electronic/telecom products. If Amazon sells 10 Bluetooth speakers in an hour, over 6 of them are sold in the emerging markets of Asia, Africa and Latin America. And English is not the dominant language of the masses in these regions.
Internalization is a key requirement in products in today’s globalized world. And the biggest change required to fit this need, is in technical documentation. Technical writers can make sure that the product is easily usable by making documentation available in the local language.
For small products with budget constraints, the manuals can be made self-explanatory through pictures, snapshots, and tables, which would minimize descriptions in words.
This is an incorrect assumption, simply because different users have different perspectives to a product. Especially multi-function gadgets like a mobile phone serve completely different purposes for different people. An official communication tool for some, a gaming console for some and a multi-media device for some others. Hence all available features, small or big need to be documented in a requisite measure. Let’s take a specific instance. Audio support for reading messages aloud is an irrelevant feature for most mobile users. But for a blind user, this feature is a make or break while using a phone.
So technical documentation must faithfully reproduce instructions for all features that the product possesses, small or big.
Wrong. Technical documentation is of prime importance to a new /first time user. Once he is familiar with the product, he is unlikely to refer to documentation again. Technical documentation must trace the activity workflow of a new user in the order in which he is likely to use the product.
This rule automatically implies that installation, unboxing related help must come first. Then instructions for first-time use – like overnight battery charge. Only then comes regular usage of the product, again in order of operation.
The technical writer who produces documentation for a product can be likened to an experienced user helping out with how to use the product, for the benefit of a first time user.
By and large, a technical writer is a proxy user. He needs to understand the workings of the product from the user’s perspective and not from the designer/developer’s perspective. Then he needs to elaborate it in words and pictures. This is why developers are discouraged from writing the documentation themselves, alongside their implementation. Because they see the product from within, not like an external user. So the technical writer’s understanding of the product must be only what a user needs to know, certainly not what the developer knows.
But there are some extremely domain intensive products, for which this statement is true in varying degrees. Especially B2B products not meant for a retail user, but for an operator/administrator user. As discussed above, a BTS equipment for 3G network setup is certainly not a common man’s product. Its users are cellular network operators. So manuals for such products are likely to contain protocol configuration, performance tuning, and other highly technical information. Hence sound domain knowledge may be required in such cases.
Catching and holding a reader’s attention is a creative business. Irrespective of whether the written piece is fiction or on current affairs or technology. The writer must have the intuitive ability to read the user’s mind. What kind of queries are likely to rise when the product is put to use, the technical writer must be able to visualize. How to present the product’s workings in a succinct and ordered manner, must be his goal.
Supporting illustrations and snapshots need to be added along with the write-ups. It suffices to say, badly constructed documentation is worse than no documentation at all. Hence technical documentation is as much a creative challenge as any other form of writing.
Like any other form of communication, technical documents are also moving with the wave of technology. From printed to online documents is one such paradigm shift. This shift necessitates the use of some online tools such as HTML/XML for web pages, Photoshop-like tools for picture editing and Dreamweaver like software for packaging the whole material. Moving even further, some products have video shared manuals for educating the user about their products more comprehensively. New age tools like Whatfix are the next generation in information gathering. The technology wave will always keep bringing new tools and methods into practice.
However, the underlying fact is that a technical writer’s core strength is his product understanding and writing skills. Any tools required during the course of their work can be mastered in a matter of weeks.
Most technical writers spend a majority of their time understanding the product under study. They are required to use the product and familiarize themselves with its workings. Next comes keeping themselves up to date with the knowledge of the associated domain, whether it is finance or IT or telecom, to which the product belongs.
Then comes designing the technical documentation package, what documents to have, how to organize the information and so on. Only after all, this ground work, does the writer actually begin to write the contents of each document. Thus technical writing teams spend only a small minority of their time actually writing.
In one of the points above, we noted that technical documentation is not just about a user manual. In fact, not all contents of technical documentation are meant for the same user. The table below lists the various type of documents that might accompany a product package and the intended user for each document, in the case of enterprise products and major solutions.
|Document Type||Intended User|
|Installation manual||Installation / deployment engineer|
|User / instruction manual||End user|
|Online help web pages||End user|
|Training Guide||End user|
|Maintenance manual||Maintenance engineer|
|Press releases||Media managers|
|Troubleshooting guide||Technical support engineer|
|Product warranty / Service contract||Maintenance engineer|
|White papers||End user|
Since different people are going to use different aspects of the documents at various phases of the product, it is prudent to separate out the content logically into separate sections or documents.
On the contrary, if there is a limitation in any of the features of the product and it is not specifically documented, the product may be rejected for failing its contractual obligations. Lack of clarity in documents about performance parameters like throughput, efficiency and load are often reasons for products failing final acceptance from end customers. Remember, the technical documentation is not a marketing tool, so glossing over inadequacies of the product is meaningless.
Limitations and precautions such as about the environment (temperature, humidity), stability (when used for long periods of time), security (data security and user access control) must all be documented with accurate details in the user manuals.
Incorrect. There is a key difference between documenting a user manual for a hardware device, and for a software installed into your computer.
Take a hardware product like an external USB hard disk. You unpack the item, pull out the instruction manual. Glance through key points, keep it aside. Then plug in the device and start using it. You might never read that manual again.
On the other hand, take a software product like Microsoft Office, which you have just installed into your computer. If you are an absolute novice attempting to create your first word document (yes, there are some left in the world!), you might click F1 for opening online help. The online help that opens gives you a general introduction first. But as you go on using the product, you have several queries. Like you how to add a picture to my document, how to create a table of contents and so on.
This is where context-sensitive help – a unique help feature for software products – comes into play. If you select a table and then launch your online help, help content, specific to editing tables will appear. This concept has revolutionized the technical writing process and made it more accessible and user-friendly.
The technical documentation team in big companies are not seen in isolation, they are considered a part of the product development team, along with designers, developers, and testers. In-depth knowledge of the domain to which the product belongs is essential to all these team members. With this key strength, information developers often transition into testing, pre-sales or customer support roles. Big companies have technical writing staff to the tune of dozens of people. So vertical growth in managerial roles or lateral movement to other products in the same domain are also attractive career advancement options.
To read more on Technical Writing, check out How Technical Writing Is Changing With The Times
Did you like our post on Technical Writing? Then, subscribe to our weekly newsletter for more awesome content.