Bob Chapman

The following is a polished version of a post I made in a group discussion on LinkedIn. In this case, a person who was about to graduate with an English degree was wondering about finding a position in technical writing.

The tool discussions you see on this thread are important for professionals currently practicing the trade. When I started writing 20 years ago, I wrote printed documents meant for long-term storage. Today, I edit screen documentation that becomes outdated at the next software release. My toolset has evolved over this time. The essential nature of what I do has not changed.

You are asking about entering the field of technical writing. Why do you want to be a technical writer? Are you trying to find a job? Are you thinking about a career?

It is fine if you are not sure of your answer. I worked in several professions since college graduation. New jobs and opportunities open. Old jobs and opportunities go away. Sometimes you really do not know what you to do until you have dabbled around. I know that would never had dreamed of doing what I am doing right now while sitting in a college classroom.

The essential nature of what I do is to communicate (not tell) technical information to an audience that includes technical and non-technical people–sometimes at the same time. My desire, my lust is to communicate this information in the cleanest and sharpest manner possible.

Some definitions of technical writing are true, even when humorous.

You may decide to give technical communications a go after graduation. Whether or not you stay in this field depends on whether you discover how much you lust after manipulating written and visual communication to an audience that does not care to read your every word. Your audience only wants to do something. Your words are the path to that goal.

Your greatest compliment lies in how little people notice your work. When this happens, support costs go down and people make good decisions. This is true whether your product is an electronic defibrillator or a SQL database app.

Sometimes your work is not where you expect it to be. Helping to design a web page user interface for a product to make it clearer and self-intuitive is as much technical communication as preparing the white paper describing the need for that product to potential customers. Depending on company size, you probably will not write the user interface and the white paper—although there are exceptions to this.

Your profession is conveying technical information. Yet, you have a concern for marketing. Sometimes you have to think like a Mad Man when all you want to do is explain the widget.

Visual communication is as important as the words you use. You have to have good presentation and layout before anyone will read your good words.

Sometimes you have technical illustrators to create the pretty diagrams and pictures. Most of the time, I create my own. Even when you do have the help, you will want to have some control over what types of diagrams used to illustrate your text. After it, this project is your baby.

Sometimes you feel pride in what you do. One of those things for me is the Boeing 777 development program. As a contractor, I did many things “inside the gate” at Boeing.

I wrote the first planning documents at Boeing for performing manual and automated system functional tests on the 777 aircraft. In many ways, these documents were wish lists by engineers dreaming about the future. As such, these documents required later revision by others, but I was Number One.

I prepared several types of documentation for the online rejection tag system Boeing implemented with the 777 program. INCA (Integrated Non-Conformance Analysis system) replaced the need to transfer handwritten information to electronic format.

The first All Nippon Airways 747-400D, Yuki's Whale

I assisted engineers from All Nippon Airways, one of the partner airlines involved with the launch of the 777, through Boeing Customer Services. My workday starting over at 4:00 pm when the telephone calls started from Japan. (This assignment also gave me a front row seat when the first ANA 747-400D exited the paint shed—the “Marine Jumbo” or “Yuki’s Whale.”)

Later, I worked at the former Kenworth truck plant that was in Tukwilla, Washington, in Planning. It is across the street from what is commonly called “Boeing Field.” One day I heard the then-unusual higher pitched whine of a 777 taking off on a test flight. My attention was drawn immediately out the window—and away from my site manager who was talking to me—to watch it take off. I apologized, briefly explaining the minor bit parts I had in that plane, and said, “There is a little bit of me in that plane.”

In 2005, I did the instructional design and production of the web-based training for the Boeing modifications to SLATE, the online systems requirements database used to construct the 787. (My title was “technical writer.”) I feel a similar pride when I see one of the 787 test planes take off from Paine Field not far from where I live in Everett.

There is one way to sum this up. I cherish the comments from a project manager that once said about a help system I created, “This is the first time I’ve seen a help system actually say something.”

That is the thanks I need.

Joe Welinske

“Development Techniques for User Assistance in Smartphone Applications” was the title of the presentation given by Joe Welinske (WritersUA) at the February 15, 2011, meeting of the Puget Sound Chapter of the Society for Technical Communication. He shared some of his observations having worked with a couple companies developing user assistance for Apple® iPhone® applications. The bulk of his comments were about developing for Apple products.

When starting, Welinske made the following points:

• Apps are becoming more robust
• Complexity and minimal screen real estate don’t mix
• Mult-touch and multi-key controls are not easily discoverable. (How do you know to “double-tap”?)
• Conceptual, contextual information is still important
• Enterprise-related apps benefit form a consistent UI

When it comes to creating user assistance, Welinske felt that using tools for creating user assistance for desktop applications did not meet the needs of iPhone apps. Even using the conditional text capabilities in tools like Adobe® RoboHelp® and Madcap Flare™ to single-source content could not fit the lifestyle and sensibilities of an iPhone app. User assistance for a phone app needs crafting to fit the situation, not building from a tool. For example, Flare will create a table of contents, but that is not what you need on an iPhone.

Some of the things he felt that fit the sensibilities are:

• Use icons in the text again. While this used to be the way to do system help, it has not been the way to do it for 20 years.
• Do not number instructions. You are probably only using three or four steps under a heading, anyway.
• Words for buttons carry much more weight. Spend the time with users to do this research.
• Add a few extra words on a page to help people understand when you have the room have great benefits.

Welinske made his point on choosing the right words with these examples:

• In an app, a button said “Dismiss” when moving a timer to the background to let you do other tasks while still keeping time. This was a major technical support issue. The word “Dismiss” did not convey to users the fact the timer was still working in the background. Welinske did user research with several synonyms to see what conveyed the right meaning. Changing the word “Dismiss” to “Hide” solved the problem.
• In an application bringing spreadsheet and document capabilities to an iPhone, users did not know what “font” meant. Do not assume people have used desktop applications before using an iPhone app. They changed the user interface text from “font” to “text.” While this may not be 100% technically correct, this did convey the essential meaning to the users.

When developing for an iPhone, you need to use a Macintosh®. You need to be in the same ecosystem. Older Macs upgraded to the following work for developing in the same ecosystem:

• Hardware/Software
  • Mac with Snow Leopard
  • iPhone
  • iPhone SDK
• Knowledge
  • Interface Builder
  • Objective-C
  • WebKit

For user testing, Welinske simulated an iPhone with the SDK on an older Mac. While you cannot use gestures on a simulator today, there is a beta version where you can use gestures with the touch sensitive screen.

A corporate server served the user assistance for the apps with which Welinske worked over the telephone network. There was an assumption you would always have connectivity when using the apps. This method means Apple does not have to approve the text. If desired, you can embed user assistance with the app, but this would require approval by Apple.

Using the “viewport” meta tag resizes your content on the browser on an iPhone. There is no penalty for using this tag when using the same user assistance text on other phones, as other browsers ignore this meta tag.

When developing user assistance for an Apple product, the tools are well defined and well laid out. When developing for a Google™ Android™ device, not so much. For one, user assistance text on an Android device goes into XML files, not into a dialog box. You also need the correct AVD—Android Virtual Device—for the right mobile device.

The specs for the Microsoft® Windows® 7 phone a firm. The Visual Studio development tools are easy to use.

My reactions to the presentation

Joe Welinske suggested crafting the user assistance for the app, while using icons and keeping content simple. Do not number lines. Also, use color instead of bold in some cases. In general, what he said makes sense. However, he suggested to do not add a period at the end of a sentence with your three or four single-line instruction sentences to keep with the sensibilities of an iPhone. For example:

Start a project

Tap +, tap a project Name
Tap Client, tap +
Type a Client name, tap Save
Select the client, tap Save

I see some accessibility issues with some of these ideas.

• This uses color in a way prohibited by accessibility standards.
• How is a screen reader supposed to get the sentences right without a period at the end?

This type of punctuation may fit an Apple sensibility, but I do not use Apple products. I may understand the meaning with the examples he gave, but it depends on each individual instruction only taking one line. Even if a good goal, can you promise an instruction will always only take one line?

While a long-time member liked the idea of using screen icons as a part of instructions again, I remember the problems in doing add them as part of the text. One of the issues is what happens if an icon changes. Considering what Welinske said about the rapid development and release schedules (weeks, rather than months or years), I see a headache in keeping the icons correct and current along with the text.

I have been wrong before. Maybe I am wrong now.

What do you think?

Contact information

If you have further questions about this subject, contact Joe Welinske through the Writers UA website, by email message, or by Twitter.

Visit the Puget Sound chapter of the STC website.

Cooperative rowing crew

A standard interview question is asking how I gain subject matter expert cooperation. I know of some people that resort to bribery (read: chocolate or beer). That may work, but that makes your success hanging on the ability to find the right commodity at an affordable price.

For me, the best way is to get my hands dirty.

That is, I do not sit in my cubicle writing email messages and making telephone calls. Along with meeting with the experts, I try to validate the information by doing it. If I successfully complete the task, then I know how to write it in my own words. Before that, I am translating the words of the expert.

Translating always is an interesting task, even if it is from one type of English to another type of English.

Besides, not everything from a subject matter expert works. I have had subject matter experts that did not know about a change made to the system, or misunderstood what they thought was the process. Getting my hands dirty meant I was validating the process.

I was a contractor at Washington Mutual during the late 1990s. This was during the first period of major expansion into California followed by the expansion into the rest of the United States. My primary task involved providing process documentation for companies building out workstations and servers for branches, and for installing those servers and workstations.

Writing the instructions to build out hardware was never ending because specific models were available for a period of about 6 months. When planning a major rollout after purchasing a new thrift institution, IBM commitment involved providing the same model server and workstation for the complete rollout. If a piece of hardware required replacement, the hope was to swap it out with the same model.

Each set of instructions for build out and installation clearly stated what model workstation and what model server it covered. The documents typically stated which rollout for which I wrote it.

One of the things I enjoyed doing was validating what I wrote in the hardware lab, particularly for the branch installation procedures. (The build out instructions were mostly where to install what model number part.) Down a floor in a windowless room, going to the lab was like visiting the home basement to work on a hobby project. Seeing I was interested in what was going on, the IBM hardware consultants gave me a lot of background information and advice. Including a lot of this information made the branch installation documents more valuable, which made the rollouts go smoother.

After practice installations involving install crew supervisors, there were rarely any corrections.

Ay, there’s the rub. (—Hamlet)

This means the first draft of user assistance for a product’s initial release should exist by alpha testing. It must exist by beta testing. This is a good thing, as all user assistance needs to undergo quality assurance as much as the software.

This requires the writer to be “in the loop” with system design documentation and change orders.

Iron Mountain SecureSync

SecureSync from Iron Mountain

From about 2001 to 2004, I was involved in creating the first release of user assistance for SecureSync® from Iron Mountain®. Customers use this online product to manage their off-site electronic media storage account. They can keep a record of what media is stored, request the return of media, store their disaster recovery plan, add and remove people on the account, and declare a disaster recovery emergency. The user assistance was web-based, created using RoboHelp®.

User assistance content

The user assistance in the system help provided three basic types of information:

• Background and general information. Define the product and its uses.
• Task information. Instruct how to perform specific tasks.
• Glossary, screen, and control information. Along with definitions, this information gave the required formats for screen controls and data files entered into the system.

Later in this post is an explanation of where I would recommend things go today.

Work with the system analysts

Frequently the job of a technical writer (or a system analyst) feels like this:

It’s not my job to run the train; the whistle I can’t blow.
It’s not my job to tell how far the train’s allowed to go.
It’s not my job to let off steam, nor even clang the bell.
But let the damned thing jump the tracks, and see who catches hell!

A writer does not decide what features the software includes. Input to the user interface is not a given, although some projects seek it.

The success of the writer hangs on the quality of the system specification documents made available to the writer. This means becoming friends with the system analysts. Being a friend means helping them do their job, because you cannot do your job without them.

Problem identification has happen when I ask the innocent question, “So how does this work with that other thing, given this?” Sometimes I find out another piece of information that reconciles everything. Sometimes I walked with the first analyst over to the cubicle of a second analyst to reconcile it. My questions have resulted in a change in specifications, working on SecureSync and while working elsewhere.

In general, the use cases provided me the basis of defining each software task. I used the screen specifications to give the format of data inputs (length, whether required, numeric or alphanumeric).

Just as my questions sometimes lead to improvements in the specifications, asking an analyst to review information for user assistance led to improvements, too. When working from specifications, it is possible to put the emphasis on the wrong place.

Change orders

There are changes to system specifications. Always. The question is whether a change results in changes to the user assistance. When creating the user assistance from the specifications, rather than a finished product, this question becomes critical to the success of the project.

Changing the version of SQL probably does not change the user interface. Changing from a screen with a page full of inputs to a wizard with multiple pages would change the user interface, by definition.

What worked the best on this project was being on the email list for all changes, so I had awareness. My manager and I could quickly dismiss some changes while seeing the need to incorporate others. Working with the analysts helped on those changes in a gray area, or if you saw what looked like a benign-looking change on the surface that might affect something else downstream.

Quality assurance

The analysts can do this, but they already know how things work. I found the best quality assurance work for the user assistance came from people from support center. They understand the people who will use the product.

At any rate, when someone is testing a user scenario, that person should verify the correctness of the procedure of what is in the system help.

Differences today

Today, I would recommend only placing the task descriptions directly into the system help. When someone has a problem, they want the solution quickly, and without lots of distractions. Give it to them without the frills. You do not need a screen shot when the screen is in front of them.

The other forms of user assistance mostly go in other places, with the possible exception of the glossary

My recommendation would be to blog the background information on a public site. This serves as a sales tool as well as user assistance.

My recommendation for the information about the screen controls would be to redo the user interface so it includes this information. Do not create separate help topics for this. This means that I, as the writer, need to have input on the user interface.

Some of the longer screens may need to become wizards. It may mean having help text display when pointing the mouse at a button (although this can have accessibility issues). But, you have happier users if the assistance is there for them on the screen to help them do the job, not hiding details in the help.

Personally, I dislike including glossary definitions as hidden text that shows in-line when pointing a mouse at a term, or some other variation on this theme. This breaks the reading flow for me. I can only imagine what it does to a person using a screen reader, assuming the accessibility of this solution (which I doubt). This is a case where I would work with the team to find the best solution for the project, such as a creative use of the HTML/XHTML <abbr> tag.

My typical response is to recall something from my high school Spanish class. We once ran across a sentence that described someone as being “as good as bread.” There was some discussion on how bread is a staple and staff of life, and this is what was applied to that person.

It was pointed out how a literal translation, “as good as bread,” did not convey the meaning to someone who is a native speaker of English. We do not use this phrase, at least in the United States. If we were translating the text to English, it would be better to say that person is “the salt of the Earth.”

Most accepted my explanation. But, I do not think most people really understood the difference.

Today I saw the Seattle Opera Company’s production of the Barber of Seville. A localization of the Italian libretto was shown above the stage, which is not unusual for an opera company to do these days. These captions provided a great example of translation versus localization.

Near the end of the opera, Count Almavira tells the notary to witness his marriage to Rosina. The notary does not want to do this, as he the reason he is there is to witness the marriage between Don Bartolo and Rosina. In response to his hesitance, the Count said (in translation), “For you two bullets in the head are waiting if you offer any opposition.”

Later, Don Bartolo complains to the notary of betrayal, having acted as a witness to the wedding. Compare the answers in Italian, an English translation, and an English localization used by the Seattle Opera Company at the performance.

(Libretto and translation from the EMI liner notes, page 118, retrieved 16 January 2011)

I think the localization text is a bit clearer to an American audience than the translated text. This also clearly shows the difference between “translated” and “localized” text.

The way it is supposed to be done.

What the project sponsor described at the kick-off meeting	What the system analysts understood	How the technical writer described it in the system help
How much targeted end-user input there was	What the developers programmed	What went to beta testing (the fix will be the release version)
What the product manager sees	What the instructional designer was told to do with the training	What was released after the budget cuts and cost overruns
What marketing advertised	When the software was released	What resulted when real customers used the software
What support is given	How upgrades are made with later releases to fix the problems	What the customer wanted

I created the initial version of this at Project Cartoon. (I made minor text changes made later for each picture, as well as improving accessibility to this web page.)

Some of the work is licensed under a Creative Commons Attribution 3.0 Unported License. View the details.

One of the typical methods of performing instructional design for adults uses the ADDIE model.

• Analysis. Know your audience. Define the behavioral objectives or outcomes for the learners. Determine the options and limitations. List the project milestones.
• Design. Document the instructional, visual, and technical strategy. Determine how to reach the objectives for the cognitive, affective, and psychomotor domains. Create a prototype.
• Development. Create the course.
• Implementation. Teach the course.
• Evaluation. Determine if the objectives were met.

While I have experience as a high school teacher, my adult instructional experience has been involved mostly in web-based training. Adult learning in the workplace is not necessarily about teaching critical thinking, particularly for web-based training. It is about learning a task or process needed in a job. Enter a prospect in the CRM (customer relationship software). Send the sales contract to billing and shipping. Change prices for a SKU (stock keeping unit). Complete the TPS report.

I joke about the difference between what a high school teacher does and what adult instruction does. Along with teaching facts, a high school teacher has the responsibility to encourage the higher level skills found in Bloom’s taxonomy of educational objective for the cognitive domain. On the other hand, teaching adults is like teaching concrete operational skills to children in the lower grades. After we finish laughing, the person to whom I am talking realizes there is some truth behind the joke.

Adults are busy. They have job responsibilities. It was a problem arranging time for the class. To quote Nike, just do it.

Creating a web-based course

Using technical writing skills, transfer knowledge from the subject matter experts to instructional content. The biggest problem is the definition of what the learner should be able to do when finishing the course. When asked, the typical response is something like “know how to use the software.” Knowing how to use the software has never made a dime for a company. Instead, knowing how to use the software (as a tool) to complete an activity that generates money is what counts. Changing from “using the software” to “completing a task with the software” is normally the hardest part of creating a web-based course.

Using video tools like Adobe® Captivate®, an instructional video can require the learner to become an active participant in the class. Enter responses. Pick choices. Lather, rinse, and repeat to reinforce the learning. Assess the learning. Gather feedback.

Using HTML tools like Adobe Dreamweaver®, the instructional videos can be a part of a complete package. For example, using style sheets, I once coded a web page with a in plain text procedure and an instructional video to print the procedure using the required Boeing proprietary and copyright markings without any of the web page chrome or video placeholder.

Using editing skills, the course uses consistent and appropriate language and branding. It communicates to the learner. It looks like it came from your company. It saves support costs.

Contact Possession Sound Technical Communications, LLC, to find out about instructional design services.

In our culture–I exaggerate only slightly–those who know cannot write, and those who can write do not know. (Norman Podhoretz, “In Defense of Editing,” various sources, retrieved 14 January 2015)

You expect documentation to do the following:

• Use the correct and consistent vocabulary and style for the intended users.
• Cover the subject completely but without wasted effort.
• Present understandable content clearly, professionally, and responsibly.

The purpose of technical editing is to do the following:

• Present information in a way to facilitate the users’ understanding.
• Offer improvements in content, layout, and presentation.

Editing Stages

A technical editor works with you on the documentation in all stages. The following is one way to organize and divide the editorial tasks:

Developmental Editing

Completed before actual writing starts, a developmental edit sets the stage for creating your finished product.

The writer, or writing team, creates a writing plan. The developmental edit looks at the plan to find to improve it to create effective documentation. The following questions will be addressed:

• Who will use the documentation?
• What is the purpose or purposes of the documentation?
• What is the style guide or style guides to be used?
• How to distribute decisions on project-specific usage (project style sheet)?
• Who will do the legal review, including checking trademarks and permissions?
• What is the appropriate output format or formats?
• What is the proposed content organization (table of contents)?
• When are the project milestones?
• Who addresses the accuracy of the content?
• How could this all or some of this content be used in the future, even if not immediately planned (localization, training, white papers, blog articles)?

Additional questions could arise during the editing process.

Depending on the project, a developmental edit process can result the following or more:

• Formatting decisions
• Document organization
• Style and tone
• Content gaps identified
• Resource identification
• Editing expectations set for later stages

The developmental edit does not enforce consistent usage, correct spelling, cross-reference checks, or similar actions in the finished product. This occurs in later stages, mostly during the copy edit.

Taking the developmental edit of the writing proposal, the writer or a team produces a draft of the completed documentation for substantive editing.

Substantive Editing

A substantive edit offers changes to make the draft effective, when necessary. To speed up later work, some copy edit matters may be identified for the writers now.

Taking the substantive edit of the draft, the writer or team produces the draft.

• Make any legal review with this draft. Incorporate the changes required by the legal review in the draft, and send the updated draft with the legal review for copy editing.
• Otherwise, send the latest draft for copy editing.

Copy Editing

When the writers believe the content is publication-ready, a copy edit verifies the text is clear, correct, concise, complete, and consistent.

The copy edit corrects spelling, grammar, and style. It verifies incorporation of the changes called for in any legal review. This step can include a proofreading, but must be clearly identified in the documentation plan.

After a copy edit, your content is ready for publication.

Light editing versus heavy editing

Performing a light edit does not substantively change the format, tone, structure, or other major parts of the content. Changes made during a light edit include spelling, grammar, or punctuation. Typically, unchanged material included in a new version of an existing publication receives a light edit.

Performing a heavy edit may result in substantively changing the format, tone, structure, or other major parts of the content.

Different content within a single product may receive differing levels of editing.

Contact Possession Sound Technical Communications, LLC, to find out about editing services.

Technical writing is the art, craft, practice, or problem of translating that which is logical into that which is grammatical. (Technical Writing, Guide ID: A425431, H2G2, BBC, retrieved 12 January 2011)

As are all other types of writing, technical writing is an art. It differs from much other writing because it conveys technical information in an understandable, direct way for the reader to take action. One of the closest relatives to technical writing is journalism.

The technical writer prepares content, as defined in the documentation plan, for storage, distribution, localization, and reuse. While writing about technical information, technical writing is not necessarily filled with technical jargon. It changes technical information into words targeted for those users specified in the documentation plan.

Writing stages

Prepare the documentation plan

Working with the other stakeholders, the documentation plan guides and defines content creation. Proper planning prevents poor performance.

Different projects require differing levels of documentation for the plan. In some cases, the project manager may define the plan for the writer. Other cases require the writer to produce a plan for formal approval from all stakeholders.

A plan may include the following, or more, based on the needs of the project:

• Intended audience of the content
• Purpose of the content
• Included and excluded content
• Content organization (table of contents)
• Subject matter experts availability
• Vocabulary list, style guides, references
• Tools needed to produce content
• Existing content and resources
• Editing resources
• Legal review
• Content delivery form and process
• Review and approval process
• Project milestones
• Publishing content
• Possible future content uses not in current project
• Content revision and retirement process (lifecycle)

This plan undergoes developmental editing and project approval.

Prepare the first draft

With a plan, the writer completes the first draft. This can involve the following:

• Interviewing the subject matter experts
• Research any related documentation on the subject
• Verify process and procedures

When complete, this content undergoes a substantive edit.

Prepare the second draft

Addressing the concerns from the substantive edit, prepare a new draft. While undergoing further edit and review, the preparation of this draft is as if for publication.

Depending on the documentation plan:

• Submit the content for legal review. Then, incorporate revisions from the legal review, and submit the updated draft with the legal review for the copy edit.
• Submit the content for the copy edit.

Prepare a publication version

Depending on informal agreement and the documentation plan, the writer may incorporate changes from the copy edit or the copy editor may make them. If the writer makes the changes, submit the content back to the copy editor for verification.

With copy edit approval, publish the content. This could be loading a PDF file in a content management system or sending the approved content to someone for publishing. The documentation plan defines how to publish the content.

Revisions

There is no such thing as a final version of the content. There is a current version of the content, subject to revision.

As such the documentation plan may call for the writer’s involvement in revising and retiring the content at a later date.

Contact Possession Sound Technical Communications, LLC, to find out about writing services.