Interview with Thomas Albert

What is your definition of technical writing?

Technical writing "translates" the engineering jargon and functional data about a technology into task-oriented information about a product that the customer uses to perform a workflow on the job. This "translation" of functional data into task-oriented information typically involves:

1. Acquiring an audience definition and a sense of customer use cases for the product.
2. Investigating the product to gain awareness of the concepts it assumes and the tasks it supports.
3. Drafting a write up that typically includes explanations, procedures, and illustrations of the use of the technology with visuals or code examples.
4. Providing use-advocacy feedback about defects or possible enhancements to the product, which might include suggestions about the wording in the graphical user interface or changes to the naming of the application programming interface (API).
5. Revising the draft as necessary.
6. Maintaining the documentation as the product undergoes updates.

What is the Research Phase in technical writing?

What would you do on the first day at work?

Begin the research phase.

1. Find any written artifacts about the audience and use cases.
2. Get set up so I can perform hands-on experimentation with the product.

What do you like best about technical writing?

The combination of phases in the process: planning, experimenting with the product (research phase), getting multiple perspectives from members of the different disciplines (development, QA, product marketing, support), using the authoring tools to synthesize all that into a practical package, getting feedback, polishing the package for delivery to customers, and maintaining and improving the documentation as user feedback comes in. In an era of specialization, such as test automation, technical writing is one of the rare crafts that involve so many phases, and that provides the craftsperson with a chance to say, "See this product? I worked (with a team) to build and deliver it!" 

Which audience do you prefer writing for?

I enjoy writing for end-users, administrators, as well as application developers.

The subject matter experts are busy people, so how do you manage to get the feedback you need?

The key is to be flexible enough to "connect" with that person. I strive to discover the best interaction style, that is to say, whether that person prefers a wiki posting, an issue logged in a bug tracking system like Jira, a face-to-face conversation, an email exchange, a telephone conversation, or a shared desktop session. Also, it helps to know whether that person is most approachable early in the morning, late in the afternoon, on Fridays, or immediately after a meeting ends.

What do you think about Customer-advocacy and Quality?

The purpose of technical documentation is to allow the customer to do her or his job effectively and efficiently. That "job" is often a set of steps, a workflow, a use case. Although the QA engineer is often a key source of information for the technical writer about the details of a specific feature, the technical writer is often the first  in-house "user" of the product from customer viewpoint, that is, from the workflow or use case viewpoint. Therefore, the technical writer's usability feedback can contribute to improving the quality of the user experience. Typically, I give feedback in meetings and by logging defects and enhancement requests.

By the way, studies have shown that users generally do not like to click a "Help" button, so calling it "Tips" is sometimes better. Best of all is when the user interface is so intuitive for the user's workflow or use case that the user never needs to read documentation. Technical writers can sometimes "embed" Help into the GUI or suggest names, phrasing, use of color, or icons that "trigger" the user's success in making the right choice. Only as a last resort should we burden the user with a topic to read. If a topic is necessary, it should give "just enough" information.

What do you think about single-sourcing?

I think it is the optimal way to be productive. While working in a markdown-to-PHP-to-HTML environment, we lacked a solution for single-sourcing. That forced the technical writers to make the same updates to different copies of the documentation, each time with a risk of information becoming inconsistent between the locations. Single-sourcing can enable us to give users the delivery format they prefer. I have seen Support users retain a preference for PDF even when Web Help is available because they are used to the PDF search feature. Many developers prefer HTML to PDF because HTML code samples are easier to copy and paste without the PDF page breaks.

What is your work history?

How did you get into Technical Writing?

I wrote my Ph.D. dissertation on the concepts of national literature, Renaissance, and Reformation, with a focus on Shakespeare and Melville. I taught composition at several colleges in the Buffalo, New York area. When it became clear that tenure-track professorships were difficult to obtain within the United States, I returned to California and found a job in a high tech start-up. This job involved writing marketing materials about digital imaging. Eventually, I published an article that made the cover of an important trade magazine, Materials Evaluation. The article, in conjunction with a contact I made at a local Society of Technical Communication meeting, enabled me to land a job as technical writer at Oracle.

How did you get into teaching Java?

I enjoyed teaching working adults since my first year in graduate school, so I welcomed a chance to do some part-time teaching of technical writing. U.C. Berkeley Extension brought me on board because I was a technical writer at Oracle and I had more than four years experience teaching at colleges and the State University of New York. When I decided to earn U.C. Berkeley Extension's Certificate in Computer Information Systems, I took courses in Java. A Java instructor told me that he had too many sections to teach. He supported my proposal to co-instruct First Course in Java with a developer I recruited. After co-instructing the course a few times, I took it over by myself.

Are technical writing and teaching complementary activities?

Yes. Technical writers rarely interact with their customers face-to-face. When I teach Java, often to programmers with many years of experience, I get first-hand awareness of how code developers learn new technologies. Teaching not only reinforces my knowledge of the material, it helps me better understand my readers.