h1

Elements of Technical Writing, Part 2

This is the second section. The first section is here

The Tasks

Tasks are the things your audience will be doing with your product. For example, setting up backup media, loading detergent into the steam cleaner, or engaging the emergency communications system. These are the activities that your documentation will describe.

Most documentation these days is “task-oriented”, which means that the writer has done a “task analysis” to identify a set of tasks that users can perform with the product. Then, the writer organizes the documentation around those tasks. Task orientation is a common and powerful way to organize your documentation. In most cases, users are not really interested in reading documentation; they want to accomplish a task. The quicker they can complete that task, the happier they’ll be.

Be careful though, task-orientation can be over-done. I have seen documentation that is simply a list of tasks with step-by-step instructions for each one. That’s fine until you want to do something the writer hasn’t thought about. Then you’re stuck unless you have some broader context about the product and what it can do. Good documentation will provide that context and will provide other material to support the user.

The major categories of supporting information are conceptual and reference. Conceptual information includes things like: planning a backup strategy, understanding how your steam cleaner works, or guidelines for declaring an emergency. Reference information includes things like: a list of command line options for the backup application, a chart for calculating how much shampoo to use for carpets of different sizes, or a table showing fuel tank capacities.

As a general rule, conceptual and reference material support the task descriptions. Therefore, you usually define the tasks first, then determine what conceptual and reference information you need to support the tasks. Once you have the tasks and the supporting information identified, you can determine your deliverables.

The Deliverables

Deliverables are the recognizable things that writers deliver to the project. For example, User Guides, Administrator Guides, Help Systems, Quick Reference Cards, Reference Manuals, etc. Deliverables may take any number of forms: printed books, glossy inserts, packaging copy, posters, web pages, wikis, help systems, bumper stickers, etc. Deliverables are usually the smallest things that have a schedule, and therefore are the smallest things that get tracked by the larger project.

At one time, deliverables were the center of the writer’s universe. They were defined in advance, and the writer, possibly with production and graphics help, created each deliverable as a unique item in one final form. While this still happens, you’re just as likely to work in an environment where the writer’s job is to create a set of more or less independent modules, often based on tasks. These modules are then assembled into deliverables late in the process, often by others. In this kind of environment, any individual module may end up in several different deliverables, and any given deliverable may have modules from several different writers.

However, regardless of the process, you still need deliverables and someone still needs to design them. You need to select a set of deliverables that work for your product, select the content for each of those deliverables, and select an organization for that content. Modular methodologies can make that process easier and give you more flexibility than you might have had in an earlier era, but they can’t eliminate it.

How to design your deliverables is beyond the scope of this section. What matters here is that there are two different perspectives you need to consider regarding deliverables: internal, how your company sees the deliverables, and external, how your customers see the deliverables.

What’s most important about deliverables to your company is that they are the objects that management really cares about. That means they will have schedules, deadlines, and they may even have individual budgets. You will be evaluated on how well you meet the schedule, deadlines, and budget for your deliverables. Often you will be judged more on these elements than on the content itself; as you might guess, organizations where this is true don’t produce the best documentation.

What’s most important about deliverables to your customers is whether or not they help or hinder them as they use your product. This is not just a question of “covering” the information. Even if all the information is there, badly chosen or badly designed deliverables make it much harder for customers to find what they need. You need to select the correct set of deliverables and then design each individual deliverable to be as effective as possible.

The balancing act between these two perspectives is to create a set of deliverables that will support your customers and will fit your companies internal needs. These internal needs include things like: existing documentation structure, expectations of the development team, and division of labor among writers. In my experience, this is not a difficult balancing act, but it does take some time and effort to do well.

The Environment

The environment is the set of tools, processes and support personnel that the writer works with. This could be as simple as Microsoft Word and a printer, or as complex as an ISO 9000 compliant process with a high-end Content Management System (CMS), staff to run the CMS, graphics designers, indexers, production specialists, sushi chefs, and manicurists. The environment also includes the skills and experience of each person working on the project.

Your environment, regardless of what it is, sets an upper limit on your team’s productivity and shapes the types of deliverables you can efficiently create. If you understand the strengths and limitations of your current environment, you can select deliverables that you can efficiently develop and avoid ones that will cause heartburn. For example, if you only have a word processor and a dot matrix printer, don’t commit to delivering a web site.

Environments constantly evolve. Even if you stick with Microsoft Word, or some other standard word processor, you will need to upgrade your software and hardware periodically. Therefore, understanding your environment also means understanding how you want it to evolve. Where do you see the products you support going? What do those changes mean to your documentation? What impact will industry trends (new platforms, the Internet, etc.) have on your work? What opportunities do you see for improving your customers’ experience with your documentation. What opportunities do you see for improving your team’s effectiveness and efficiency?

As a manager or writer you should know where you want your environment to be in the next few months and years, and you should be planning how to get there. If you don’t, you will quickly find yourself with obsolete hardware, software, and writers facing a potentially wrenching change, usually in the middle of a major project.

While you need to be constantly evolving, beware of big, abrupt changes. It’s very easy to be seduced by the siren song of software vendors and decide you need to completely revamp your environment and install the latest greatest XML all-in-one CMS-vegamatic solution next week. Resist that urge.

Change in your environment is one of the toughest things to deal with as a manager. People are amazingly adaptable, but at the same time they are amazingly resistant to change. Once they have adapted to the current environment, regardless of how bad it is, they will be reluctant to change, even if the promised new environment is better. The result is that a major change in your environment will take at least twice as long as your most pessimistic estimate, and the benefit will be at best half of what you were promised.

Instead, if you introduce changes continuously, you get everyone used to the idea of always looking for and implementing improvements. Then, when the time comes for bigger changes, you will have a team that is used to constant change, albeit small, and open to improvements.

Evolution in the environment also includes developing your team professionally, for example by giving them opportunities for training. The skills of your team are as important, if not more important, than any tool you can buy. The bottom line is that you need to thoroughly understand the strengths and weaknesses of your environment, including your team, and be constantly improving it in manageable increments.

The Schedule

The schedule and deliverables are the most visible parts of your work inside your company. Therefore, while they may not be the most important aspect of what you need to deliver, they deserve careful attention.

Schedules are the closest thing to a “black art” that you’re likely to deal with as a documentation manager. So, the good news is that as a documentation manager, you will rarely set schedules. The bad news is that you will rarely set schedules.

My experience is that it’s unusual for a documentation manager to have significant influence in setting project visible schedules, with the exception of the documentation production back-end. Project managers understand that some time is required to produce documentation, paper or electronic, so even though they will push to make that time as short as possible, they will concede that some time is needed. However, I’ve never seen a schedule lengthened solely to give writers time to create better documentation, and I’ve never seen a project delayed by documentation, except when the back-end processes hit a glitch.

Therefore, your job as either a writer or manager is less setting schedules and more determining how to fit enough work into the time given with the resources available. If you can’t create quality documentation in the time give, then by all means speak up, but at the same time, try to figure out how you could complete the job with additional resources in the same schedule. You’ll probably find that it’s easier to get additional writing resources than it will be to get more time.

While you’re unlikely to be able to lengthen a schedule for documentation work, you can take advantage of slips caused by other factors. If your organization “reliably” slips schedules, then you may want to quietly factor likely slips into your planning. I’ll discuss this in more detail in a later section.

Putting it Together

Being successful as a technical writer or manager of technical writers means not only mastering these elements individually, but also mastering the interactions between these elements. Every situation provides a unique combination of elements and requires a unique response. While I try to give good general advice throughout this book, it’s important to recognize that one size does not fit all. You will need to gain experience and apply that experience, making lots of mistakes, to gain proficiency.

If you’re a new manager, especially one who has little or no previous experience in documentation, you might find it useful to think of these elements as checklists for asking questions and learning more about what your team is doing. You rarely can go wrong asking your writers to tell you about the audience, or what the product does (unless it’s a toaster), or how they plan to organize their deliverables, or whether they’re comfortable with the schedule. In fact, if a writer or for that matter an interviewee can’t answer basic questions about these elements in his or her work, I’d raise a red flag.


5 comments

  1. Really useful article. Even for someone who’s been in the field for years, there’s a lot here. The parts I already knew were still good to go over.

    There’s a ref above to ??? (“I’ll discuss this in more detail in ???.”). Please update it.


  2. Melvyn,

    Glad you found the article useful, and thanks for catching the bad link; I’ll fix it, though right now the section it points to is not on the site:).


  3. […] are some highlights from the posts on Elements of Technical Writing and particularly  in Living With Technology that were quite an interesting read Evolution in the […]


  4. I’d love more real life examples of your experiences pulling each of these elements together with others and how you handled different situations with your team.

    Very helpful article. Thank you!


    • Erin, Thanks for the comment and suggestion. I’m thinking of doing a second edition of the book this excerpt came from, and I agree that this is the kind of content I should be adding.



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: