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:
|Who is my audience?||Is the end-user:
What is the audience's level of technical expertise?
|What are the use cases?||What specific tasks does the customer need to do? The documentation needs to support the most common and critical use cases.|
|How does the technology work?||By hands-on experimentation, I learn in detail the steps I need to document. Often, I discover issues that I can report to the team's bug database.|
Begin the research phase.
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!"
I enjoy writing for end-users, administrators, as well as application developers.
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.
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.
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.
|2003 - Present||Java Instructor, part-time, for UC Berkeley Extension, 30 evenings per year in San Francisco|
|November 2013 through March 2014||Terracotta Inc., a Java-based start-up in San Francisco that provides Big Data technology on top of open-source Ehcache. Due to the start-up being acquired by a large German firm that tends to centralize and downsize its acquisitions, Terracotta lost its CEO, head of engineering, and various other staff members, including me. I was nevertheless awarded a bonus for having done good work.|
|August 2010 - October 2013||Accelrys became the name of the Symyx when two companies merged and
the headquarters moved from the San Francisco Bay Area to San Diego. I
was offered relocation to San Diego but chose to resign so I could join
Terracotta Inc.and remain in the San Francisco Bay Area. I worked on
|April 2007 - August 2010||Symyx became the name of MDL Information Systems when two companies merged and the headquarters moved from San Leandro to Santa Clara.|
|June 1994 - February 1997||Oracle hired me to update networking and installation guides for the Porting group, and later I transferred to the core database group.|
After I wrote my Ph.D. dissertation on the mutual influence of the relationship between cultures and their national literatures, I taught composition at several colleges in the Buffalo, New York area. When it became clear that tenure-track professorships were difficult to obtain, 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 https://www.asnt.org/MajorSiteSections/Events-and-Publications/Materials%20Evaluation. 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.
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 several years of university teaching experience. 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.
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.