Whether you're writing software manuals, online help, brochures, or scripting a video, the core goals of technical writing remain the same, the technical writer must learn to understand the technology, develop a body of information that can help the end user to understand and use the technology, then package and deliver the information to the user. Let's consider each of these steps individually.
Before you can explain the function and use of a computer program or piece of equipment, obviously you should be able to understand and use it yourself. Having background knowledge of the field you're working in will be a big help here. If you work for a software company as a technical writer, you don't necessarily need to be able to program a computer, but understanding something about the programming process can be immensely helpful both in relating to the programmers you will work with and in understanding the product your company produces.
As a technical writer for a hardware or equipment manufacturer you may be expected to perform basic maintenance on a product, or perhaps be capable of some assembly and disassembly. The more knowledge you have about your product, the better.
Technical writers beginning a documentation product will often get much of their information from subject matter experts, or S.M.E. (often pronounced "SMEEZ").
[Note: Since S.M.E. as defined here, is plural (experts), no 's' is added to the abbreviation in this article. Just read S.M.E. as a plural.]
The S.M.E. are generally members of the design and development teams on the project. They are the technical experts with a thorough understanding of how the product is designed and what it is capable of doing. They will know what improvements the company is trying to make over earlier models of the product, and how these improvements are being implemented.
One of the technical writer's main roles is to interview S.M.E. and translate their technical knowledge of a product into more generally digestible knowledge that will benefit the end user. If you are a member of the design team yourself and are tasked with doing the technical writing as well, this step will obviously not be as important.
Since, as the technical writer, you are in charge of writing the manual, you will find that there is no manual to help you as you learn how a given product works! The S.M.E. will come in handy here as well, giving you information on how to use the product so that you can get up and running with the task.
Ideally, you will have time to play around with the product yourself, and learn by trial and error how it works. Doing this has advantages over working strictly with S.M.E. because by acting as an end user you will get an idea of what aspects of the product's use are simple and easy to understand and which are more confusing. When you write your user help, you will know which aspects of the product's operation will require more explanation for the end user. Remember that if you do have trouble learning something, it may not be your fault, but the product's.
While you learn, practice meta-learning. Be aware of your learning process. What aspects of the product interest you the most? The least? How similar or different from related products is this one? Document your learning as well. Take notes on what parts of the process you find the easiest, and which are the most challenging or confusing. If something seems excessively confusing to you, it might be the same for the end user. Bring any major concerns about usability to the development team leader. Essentially, technical writers are beta testers, or trial end users, for a new product, and quality design teams will take their concerns seriously.
Speaking of beta testers, does your company have a small group of dedicated users who regularly get first crack at trying new products in exchange for feedback on them? If so, they can be invaluable partners for the technical writer in evaluating the learning challenges that new users of your product will face. Talk with beta testers if you can. If beta testers are not the norm in your industry, ask your supervisor if you can speak with users of your company's earlier products. Users who have contacted the company in the past with both negative and positive feedback can be a tremendous resource for the technical writer trying to serve customers and to help a new product succeed. Of users who have complained, how many could have been satisfied if the company's help system was more complete? What can the technical writer do to allay any confusion that may have arisen during the company's prior product releases?
Once a technical writer has developed a good understanding of the product, the next goal is to consider the audience. How does the company define its market? What is the general profile of the company's customer base? Do its products appeal to a general audience or a sophisticated group of experts in a given field? Is the average user tech-savvy or a technological newbie? In some cases, companies will produce a range of products for users in all of these different profiles, and the technical writer's job is to deliver information that has the proper amount of complexity. If the information is too technical for the audience, they will become confused and fail to get the most out of the product (or jam the company's customer support lines with questions). If the information is too simple for a sophisticated audience, they may be insulted, and they may wonder why the manual only explains simple procedures and leaves out the more complicated and the more useful ones.
The technical writers who are beginning a documentation project should ask themselves what general level of skill the end user is likely to have? Which terms will be generally understood, and which will require definition? It may be wise to include a glossary somewhere to explain any terms that may not be understood by everyone.
The term deliverables is used in technical writing to describe the format or formats in which the writer's output will be produced. Traditional deliverables included hard copy owner manuals, product specifications, and other paper based documents. Nowadays, these kinds of documents are often published both on paper and in a pdf file available on the Web. Many companies don't publish hard copy help at all anymore, instead, they may include a CD containing the manual in pdf form. Other companies strictly offer support and manuals on the Web.
As technology enables the affordable production of audio-visual media, more and more audio and video tutorials are becoming available. Depending on the type of product, these can be far more effective methods of teaching people how to use a product than simple words on a page or on a screen. The modern technical writer may find himself producing instructional videos more often than written help. For software products, specifically, screencasting is a growing type of technical help, in which an end user is shown a video on their screen of someone actually using the software. The user can then follow the process visually and this can result in a much better understanding of the product.
With the advent of Web 2.0, more interactive forms of user documentation are beginning to appear, such as wikis, which allow users to contribute to user's manuals online, and blogs, which enable technical writers to publish helpful information and respond to customer questions on the Web.
The kind of deliverable which is suited for the project varies by product, the type of user, and other factors. Currently, online help doesn't work for the average driver in a car, so car owner manuals are likely to be produced in hard copy for the foreseeable future. Software, on the other hand, is very often downloaded directly from the web, and not purchased in a box from a store. It makes sense for the customer support materials to be available online for these products as well.
In most cases, technical writers will be called upon to package several different deliverables for a single product. A computer may have a printed manual, a shorter quick start guide, an online version of the manual, and an interactive website offering help as well. As the range of media widens, technical writers are looking for ways to single source, to organize their content in a way that allows it to be published in a variety of media without being rewritten.
As with any major writing project, it is wise to organize the material the technical writer has gathered from S.M.E., other users, personal experience, and so on, into an effective record keeping system. A set of folders on the writer's hard drive as well as a filing system for any handwritten notes and other hard copy data for keeping track of all of the information the writer has gathered about a given project. When the time comes to produce a deliverable, the writer can further organize their content into a project outline, video script, website map, or other blueprint for the finished product. In the case of a single-sourcing system, as mentioned in the preceding paragraph, the material may be organized by topic and written in a computer language that will enable it to be published in a variety of sources.
Often, the technical writer will work in a team environment, either at an office or virtually (online). Regular feedback will be a normal part of the procedure and the writer will have plenty of opportunities to offer their work for coworker review. Drafts of the deliverables should be forwarded to S.M.E. for comments and revisions during the writing process. If a writer is working virtually, it is still important to get feedback on a regular basis, especially if the technology involved is new to the writer. The sooner a factual error is caught and rectified, the better.
