Effectiveness Workflow for a Technical Writer

By Aisoorya Vijayakumar

I can almost read for certain the thought that runs on your mind as you are reading this – “Alright! Here’s another nagging post on how I need to start and get on with my documentation…!” I would have empathized, and on a sunny day, even applauded you on guessing it right, had I not had the home advantage of knowing that this is not another run-of-the-mill post on the much-beaten-to-death topic on how one should do authoring.

If you are a writer well on to the second half of your decade-old technical writing career, let’s take one moment to recall those initial days of frustration and struggle when you wished for a miracle to fall through the roof and help you get a grip on how and where to begin. We all have been through those moments of cluelessness where we ended up with nightmares of distressed customers chasing us with cannon balls. Now, having got a reasonable idea on which potholes we need to look out for and which potential demons we need to slay, we take on our writing duties with more confidence.

But if you ever happen to notice the face of a newbie who has joined your team, and observe the collage of expressions he or she seems to give, you would be able to notice his or her haggard emotions ranging from confusion to absolute dread. This post is more of a ready reckoner intended for any person with newly bestowed authoring duties.

Authoring invariably tends to flop because of lack of proper homework. With all the enthusiasm reserved for a young tender mind, when a writer holds his or her breath and takes a plunge into the deep sea of documentation, with no proper deep-sea diving gear, the sea would turn deadly in no time and would choke the life out of the writer. Taking a moment to learn the steps involved in the workflow of authoring a well-churned-out document would help immensely in the long.

Setting Sail

Points with which we begin our authoring journey…

Let’s say you and your friend are off on a long safari trip in Amazon. While you believe in just backpacking, throwing darts on a jungle map, and stopping at every village that the dart lands on, your friend believes in making a study of the place, being well-informed on local cultures, understanding about the indigenous wildlife, and then making the trip loaded with reserves for all possible emergencies. Given, your method may look tempting to begin with – no groundwork, no worries! But if you reflect on this carefully, you cannot deny the fact that your friend has probably more chances of surviving the dangers in the jungle, while you might probably end up as breakfast stew for a local tribe, or the dinner dessert for a lurking lion. While getting into the job on an impulse may suit some vocations, we need to be clear on the point that documentation is not one of them. Here, it pays to be prepared. Hence, before you begin authoring, just keep an eye on these following points.

Audience Analysis

Understanding your audience is key to your success as a technical writer. Not really knowing who you are writing for, makes you vulnerable and prone to criticism or indifference. Keep in mind the following:

1. The audience preferences tend to be startlingly varied, based on their geographical locations, language use, heritage, culture, customs, beliefs, and so on.
2. Remember that your bonding with the audience does not end with the authoring phase.
3. Keep a tab constantly on how comfortable they are with your documentation and how better they would like it to be. Most organizations have customer forums and conference calls where the customers get to express not just their delight, but also their angst if any, on the products and the end user documentation. Start using such forums to your advantage and your document is already on the winning path.

Choosing and Customizing Your Authoring Environment

Never underestimate the importance of doing a good research on the authoring tools available in the market. This link provides a comprehensive insight into the various Help Authoring Tools (HATs) available. There is a myriad of authoring tools, with the number increasing every minute of every hour, with diverse uses. So, if a single-source, multiple-format-output need is what you have, choose an appropriate tool, instead of going for a single output tool and then spending further money on converting that output into other formats.

It is equally important to tailor your authoring environment to suit your need. Think of the authoring tool as a sweater. The sweater is not going to keep you warm and snug until it is the right fit. Making sure that your tool fits your needs aptly, is as important as this. If you intend to use an XML authoring environment, this publication by the Wisconsin chapter of the Society for Technical Communications (STC) will be a handy aide.

Progressing Towards the Horizon

Strengthening and enhancing authoring efficiency…

Now that your armor is ready for the battle, you are all set to take the firing head on. You just need to remember a few basic protocols. And trust me, following a protocol is no menial task. It comes in very handy. Even army folks memorize their protocols and commands, arguably to ensure they don’t misinterpret a command that the captain shouts and end up butting their rifles on the captain’s head instead of the enemy’s.

Information Gathering

How do you know where to begin and where to end your document? How do you get enlightened on what the scope is? How do you know the type of document that your project needs? How do you know whom you need to turn to for technical information? You won’t know any of this until you gather some elementary information on the project requirements. Do not wait for the information to reach you on its own. Take some initiatives, check your technical teams for spec files or design documents, get started on understanding the logic behind the product, pour some energy into the project, and see the difference it makes to those involved.

Gain a Good Standing on the Technical Know-how

Yes, your technical teams would give you knowledge sessions on the product. Yes, your SMEs would always be there to respond to your questions on the product. And of course, yes, you would always have the technical spec documents to fall back on, for any dearth of information. But none of this can compensate for the rich understanding you’d gain, by playing around with the product yourself. If you are documenting for software application, talk to your engineering team, get yourself access to the application and then start using the application. Ask yourself questions at each step on what you are struggling with, and what kind of information in a document would help you with that particular problem. This makes your documentation technically crisp, in turn reducing the time and effort you would ideally spend for reviews.

Set Contribution Expectations Clear with the Technical Team

It is very important to let your technical team – developers and testers – know what help you’d need from them to help you write better. If you were expecting any specific technical inputs, it would be good to give them a set of precise questions for which they can frame answers. You also need to let them be prepared with their post-authoring review duties. Don’t spring a surprise on them one fine morning expecting them to review a 50-page document in a day. Let them know that you’d send out information in manageable chunks, as and when you author them, and give them a sample of the review comments, you are expecting. Give them considerable time to do a detailed review and mail you their comments or talk to you about their comments over a review meeting.

Flagging the Destination

Winding up and analyzing end results…

Once the document is ready, do resist your urge to share the document with the reviewers and editors right away. A very important, but often overlooked step in authoring is self-validation of your documentation. Do a reverse review (from the last page to the first) to check for the spelling and a forward review (from the first page to the last) to check for improper information flow and sentence construction.

Once you pack your document off for reviews, and all the pieces are in place in the puzzle, jot down your learnings and key take-aways while you await review comments.

Some points to be penned down that may come in very useful later on, could be:

1. Get key terms ready for an index or a glossary if your document would have one.
2. Document important issues you faced with the authoring tool and their workaround solutions.



3. List down points of contact from the technical team and their contact details. This would be of good use when you transition the project.

…And there you go! You are done with authoring a document as effectively as anyone can and you can pat yourself for a job well handled.

Note: All graphics have been sourced from Novell. Copyright infringements are prohibited.

About the Author

Aisoorya Vijayakumar, a Lead Technical Writer with Novell, has close to six years of experience in the field of technical communication. She has worked extensively on technical learning modules and end-user product documentation. In addition to her primary documentation responsibilities, she takes care of patch release documentation management for her team at Novell.