Newsletter Essay - Technical Writing
By William PacinoIf you, as the technical writer, have been on an interview lately (who hasn't?), a question that always comes up, is "Tell me how you work?". I call this the "explain-your-methodology" question.
Being an experienced technical writer and editor, a technical illustrator and a production editor when the project calls for it, what do you say? What is your response when you are asked, "How do you write a technical book?"
This question, along with the questions on how do you deal with people, (How do you get along with your peers? How do you work with the software and hardware engineers who contribute the information that you prepare as a technical writer? What do you do with someone who is not cooperative?) are answered with experience, the experience of trying and failing, trying again until succeeding.
Very simply, you, as the technical writer, have to know where you are going before you take off. You need to know the total picture of the job you have been hired to do. You must plan the work, outline the changes, and anticipate the preparation of items that need more time to put together (the so-called "long-lead items"). You need to research what has been done before (there is always a "before" in technical materials), and you must interview all parties to the project you have been assigned to.
Important interpersonal skills include the ability to listen to what others tell you, to respond and take action on others' words (not always follow your own agenda), and the intelligence to sort through more information than can be used. The user of the books, CDs, Web pages that you are preparing (the audience) needs only so much. You have to dial in on what only-so-much is.
Economical personal work habits will also serve you well - work habits that use the limited time and space that is the rule within technical documentation preparation. Retrieving the wrong version of material from the stack of paper in your cubicle, or having to redo artwork because you can not remember where you saved it is not a good use of your time. Reformatting pre-existing material, just because you do not like the old format, without adding any more value, is a waste of your time. Of course, not everything assigned to you will be state-of-the-art, cutting-edge, portfolio-quality work. Yes, there will be the mindless retagging or clean-up needed by some projects. Again, the key trait is to use your time and space wisely. Figure out the way to get through the undesirable task quickly and on to something more profitable.
I have tried to present what I have been using to plan, research, interview, prepare, review and print technical documentation. Some of my comments are opinion - you may or may not agreed.
If you can get into words all the information that I present, and your interviewer is still awake at the end of it, you really have it and certainly merit the technical documentation position you are pursuing.
As a way of showing how formal technical documentation can be, look at the flow chart below, dating from the 1970's, showing Editorial Procedures divided into four major phases and sixteen functional blocks. A series of tables following this flowchart list the detailed sub-steps within each phase. This flowchart is reproduced to illustrate the extensive steps (whether you realize it or not) that go into preparation of technical material. Of course, depending on the company or industry, many of the technical document preparation roles identified in this flowchart have disappeared (a specialized Copy Preparation/technical typing group; an art department (twelve artists in a room working off of oversize artboards); even technical editors).
In many places where I have worked, the surviving technical publications role is that of the technical writer/author. The phases and the functional blocks (tasks) of documentation remain however, and, if you are the technical writer, trying to complete all of these tasks is how you do the job.
After the flow chart and the tables of sub-steps, I return to my presentation of what I have been using to plan, research, interview, prepare, review and print technical documentation.
Figure 1. Four Major Phases and Sixteen Functional Blocks of Editorial Procedures
The sub-steps (functional blocks) within each phase of the flow chart on the previous page are listed below.
Accepting the Document - Phase 1
Preparing the Manuscript - Phase 2
Preparing the Printing Package - Phase 3
Document Delivery - Phase 4
Someone is calling for your services. Either your technical documentation manager assigns you based on your availability; someone sees your listing in a freelance writing publication; or a recruiter calls you up after finding you in the recruiter's database.
This is an area that you, as the technical writer, can either move through quickly, or can spend a great deal of time on. The organization you are working for, at some point, mandated a particular format and style to apply to all materials. This was done to make the materials - be they engineering, marketing, manufacturing - look more professional. When a customer or prospective customer gets sales, marketing and engineering materials that all have a common look, a judgment can be made that the company producing these materials has its act together.
However, you may get into a situation where the project is open to a different appearance (format and style). In all likelihood, there will still be a need for manuals (hardware, software, service), for marketing data sheets and briefs, for primers and white papers. My suggestion is to construct documents (format and style) for the use that customers have come to expect.
Also, be aware of the multitude of uses one piece of writing can be used in. For example, a white paper or primer can be used a printed marketing piece or a instructional piece on a Web site. The same material could end up as a technical article in a trade magazine, or be placed in a technology basics section in the appendix of the user manual. Prepare materials with portability in mind. Do not overformat your information, making it too hard to use elsewhere.
Know where the product is going before you take on writing, editing and illustration tasks. A knowledge of the big picture comes from preparing a plan and outlining all the requirements of the project. Prepare a documentation plan by defining the following elements and tasks:
· Product name; Document Title; Part Number; Edition; Software Revision Number
· Document Type; Document Purpose; Audience; New/Update/Replacement?
· What are the other pieces of documentation set/ Complimentary documentation
· Translation Needed?; How will the document be delivered (paper, CD, HTML); Number of copies
· Detail the Engineering Specification and Functionality documents that will become the source material for the technical documentation requirements of the projects
· Detail where changes need to be made or new material to be added
· Who is to Review and Sign-Off Approval on the documentation; How much time is available or required for the review of the documentation
· Prepare a Schedule of Time needed for documentation-related work. See the sample table below.
|
Deliverable |
Percentage Complete |
Date Started |
Date to be Completed |
|
Project Started |
0% |
||
|
(1) Initial Research (2) Design (3) Doc. Plan |
10% |
||
|
(1) Research (2) Write (3) Edit (4) First draft produced |
40% |
||
|
(1) Reviews by Engineering (2) Doc. Edits (3) Second and final draft produced |
65% |
||
|
Final Sign-off |
85% |
||
|
ER (Engineering Release) - Engineering has completed the project. |
100% content 90% (printing) |
||
|
First Customer Shipment - books, CDs, printed material needed to be placed in shipping package |
100% (content & printing) |
Realize that not everything is written down in easily-obtainable documents. Yes, I have been in situations where the Engineering Specification documents were so good that the manual was written right from the documents without any hands-on work on the product.
However, in most cases, there is a need to talk with the engineering staff, to ask questions, to seek their help in getting you into the appropriate areas of information. Having an ability to audiotape or videotape interviews is helpful in capturing technical information. Take notes on everything, including instructions. Attend product and prototype demonstrations. Having too much information initially is far better than not having enough.
Know your product - use it, read about it, experiment with it.
Collect previous documentation, related documentation, and documentation on the same type of product from competition. Be open to pieces of incomplete information that circulate in electronic mail (e-mail) or voice mail.
As stated in an earlier section on portability of information, think in terms of what marketing, sales, or other engineering information could be used. It is much easier to add pre-existing, reader-tested material than always writing everything from scratch.
Who are you writing for? If you don't know, you can not write anything of value. In the first meeting with your project team, ask "Who is the audience for this book?
To re-emphasize an earlier point, your time and space as a technical writer is limited. If you have a sophisticated, knowledgeable audience, you can write less on certain subjects and move on to other more-pressing needs. If your audience is novice, you need to bring out all the firepower you can muster -- charts, navigation maps, detailed menu representations, extensive glossary and tutorial sections, technology primer, etc.
Look for a summary of changes to come. No project development or revision is endless. There is usually a customer need to add a certain amount of new functionality to a product. Know the amount of information to be added. List it as completely as you can, marking the spots in the existing documentation where the new or revised to be added. This listing is usually found in the documentation plan you prepared, so that you knew what you were getting into and what deliverables are. You did do that doc. plan, didn't you?
This is where you read intensely the EIS (Engineering Interface Specifications) documents. Yes, there are engineers who can write. Use what they wrote to explain to the user and reader what the product can do. If the EIS does not give enough detail, you will have to return to the interview/ research aspect of technical writing.
Again, the Human Interface Functionality documents need to be read and re-read for what the software will do. The same statement used one paragraph above for hardware applies to software as well. Software is very important to a technical writer, because software is visual, that is, its results produce screens, tables, diagrams, that the user/reader of the manual can see. Charting what is visual, what can be seen by the user, is an important part of writing/preparing documentation.
If the product has a physical dimension, work through the softkeys, pushbuttons, dial tuners, switches - everything that you can touch, push or pull. Represent what the user sees when looking at the front panel and rear panel. Connections, fans, safety information on the unit should all be shown in the technical manual. Use photos and line drawings. Be aware of the file sizes that certain photo and drawing formats use. You may not have enough computer or file space to manipulate these materials. To re-emphasize an earlier point, try to work economically.
If the product is software, work through all menu screens using whatever user interface is utilized. Capture the screens and use them in the manual. Tell the user what the screen is and how you got it. Screens without a sense of where they came from do not help a reader who does not know as much as you do.
Be open to pieces of incomplete information that circulate in electronic mail (e-mail) or voice mail. As a project is going on, there is usually instances where the engineers are working towards a solution, and the technical writer is sitting in the background, working on a unit to see how such-and-such functionality works. The engineers will discover something of value and will call out to the technical writer, "Hey, make sure what we just discovered is in the manual". Taking notes on everything and saving the notebooks is highly recommended.
This subject deals more with electronic ways of presenting information, besides printed books and manuals. On a CD or on a Web page, a navigation map is needed. The table of contents and index helps. But having a way of telling the reader what each section contains and a way to get to that section or material quickly is important to the reader.
A technical manual is not read from front cover to rear cover. When someone picks up a technical manual, they have a problem and are seeking a solution. The faster the manual gets the reader to what they want, the better the manual is. Of course, one way to aid the reader is to break up the material, putting Getting Started material in some thin booklet; programming commands in a separate manual; and other specialized information in other appropriate publications.
I made the point earlier. Do not overformat a document. Do not reformat material without adding some other value. There are so many uses of one piece of written material. Do not hurt the portability of your technical materials by making the effort too hard to move it from one form of printed or electronic publication to another.
The four phases and 16 functional blocks of a formal editorial process were presented earlier in a flow chart and tables. The total process still applies.
To catch all the spots where errors can be made, it is necessary to review the material in a multitude of passes. The first pass might be solely to check page numbers, or page breaks, or headers/footers. Other passes would be to check figure and table numbering, or text callouts of illustrations and tables. More passes would include checks for grammar and spelling. When you finish making the changes from one draft, print out the new draft and match it against your previous draft. Make sure you picked up all the changes. Editing can be tedious, but every time you find an error, your time has been well spent.
The people who are the members of the project team need copies of your manual so that they can make sure that you understood the required technical changes. You desperately want others to review your work. Nothing personal is meant by the following statement, but you, as the technical writer, never know enough about the product. If you did, you would be an engineer on the project, not the writer. Having the entire project team read the entire manual is the most ideal form of review. But if you can make sure the appropriate person reads and reviews the appropriate section, you have done your job.
Make sure the review period has a fixed end to it. Getting changes from others, getting ready to go to print, and having a late reviewer pop up out of the weeds with an extensive set of changes and further questions to ask of others is not fun.
Right from the beginning of the project, when you are preparing the documentation plan, find out who has final sign-off responsibility on the technical manual. Know their schedule of availability when the technical book is due to go to print.
Your manual can be delivered in many different ways (paper, CD, HTML). During the documentation planning period, make sure you know what the delivery form will be. Paper, CD, HTML, online help all use the same information, but certain differences in writing and preparation are needed.
Be open to the errors that others discover when using the material that you have prepared. Return to a listening mode for suggestions or complaints users have. There is always another revision.
When someone now asks you, "How do you do your work?", hopefully you will remember this long answer on the ways to plan, research, interview, prepare, review and print technical documentation.
You got it all, didn't you?
= = = end = = =