My technical communication contribution to the UX Careers Handbook
Here’s the book:
What does UX Careers Handbook contain?
The UX Careers Handbook offers an insider’s look at how to be a successful User Experience (UX) professional from comprehensive career pathways to learning, personal branding, networking skills, building of resumes and portfolios, and actually landing a UX job (Read more in the content preview)
You can order the UX Careers Handbook from Amazon here.
There’s also an online resource section for tech comm here.
The section I contributed is on technical communication, which I was pleased to see included in the user experience careers. I asked Cory if I could also publish the section I contributed on my blog, and he said I could. Here it is.
Technical Communication
by Tom Johnson, Senior Technical Writer
As a technical writer, you help people understand complex technical information. In the United States, many technical writers work in a variety of industries creating documentation, especially for software applications. For example, when people click the help button in an application, your documentation appears and helps guide them through tasks.
If you work in manufacturing engineering industries, you might create documentation for machinery, medical devices, consumer goods, or other physical products. In this case, your user guides often ship with the product.
In any company that employs engineers, you will probably also find technical writers, because technical writers provide the documentation that accompanies products that engineers build. You might create reference and user guides for software APIs, work on massive projects such as providing maintenance guides for aircraft, or write troubleshooting articles about mobile devices for help center agents. The number of contexts for technical writing is as diverse as the technology landscape.
Regardless of the context, the end result is usually the same: Through the documentation you create, users learn to use applications or products efficiently to accomplish real-world tasks.
What does a technical writer do?
Create documentation
Your principal deliverable is usually documentation for a product, published as an online help site or printable user guide. The documentation primarily focuses on tasks that users perform with the product. You also typically include conceptual information related to your users’ goals with the product. Your guide will most likely have a table of contents, a search feature, cross-references, screenshots, and navigation, among other features.
Contribute text for the user interface
Beyond creating documentation, you might also shape the text in a software interface, including error messages, tooltips, button names, getting started text, and wizards. Unlike with content in a user guide, you may have to make a persuasive case for some button names and labels. This is because there are more competing stakeholders with the user interface than with the user guide text.
As a master of language, you can play a vital role in shaping the language used in the user interface. In many cases, users never leave the interface, even when they get frustrated and need help, so this is a key area where you should focus your efforts.
Make information visual
Nothing turns users off more than long walls of text. To help users understand complex information, you supplement your text with screenshots, conceptual illustrations, video tutorials, diagrams, workflows, and multimedia graphics. Even with areas of text, you still make it visual by adding bulleted or numbered lists, subheadings, callouts and notes, paragraph breaks, sidebars, and other visual elements. Making documentation visual helps make it appealing and readable.
Create strategies for content re-use
In addition to creating content, you also employ strategies for reusing the content across different deliverables. For example, you may need to provide 5 different variations of mostly the same content for different product versions and audiences.
Rather than primitively copying and pasting content from one output to another, you reuse content using special tags, and add product and audience attributes to the content to filter the page when you specify your output. Reusing content reduces inconsistency and minimizes word count for translation.
Set up authoring and publishing tools
In addition to creating content, you also set up the tooling to support authoring and publishing of the help content. Whether you’re using a help authoring tool, wiki, custom website, or other platform, you often need to set this up. You might configure access rights, set up search, construct documentation portals (home pages for lots of different guides), design the style sheets, and more. Deciding which publishing tool to use based on your requirements is a decision you may also make.
Challenges
Understanding how a product works
Before you can write documentation, you have to figure out how your product works. You might wade through poorly written specifications or other engineering documents to gather information. You might explore the product through trial and error, or look over the shoulder of engineers as they explain how something works. Just figuring out how a product works can take weeks of meetings, explorations, and interactions with team members.
Getting information from engineers
You need to interact heavily with engineers, who may or may not want to take the time to explain things to you. Engineers can also be unreliable in estimating what users need to know, so you’ll have to assess what they say about the level of information your users will need. Therefore, you need good interviewing skills and must be comfortable asking questions until you understand the product well enough to explain it to others.
In addition to talking with engineers, you also have to interact with users to understand their business goals, level of knowledge, and other needs. You might interact with users directly, such as in training sessions or on-site visits, or indirectly through forums, email, and support logs.
Working in isolation
As a technical writer, you work long periods of time in isolation, often in front of a computer. You may be the only technical writer in your organization, immersed in a department of engineers who constantly speak in programming jargon that you may not initially understand. Even if there are other technical writers, you may not get to work with them, as you could be assigned to different projects. Expect to find yourself in situations where you work alone for long periods of time.
Working in teams
Although you may spend a lot of time working by yourself, you may also be part of a larger team. You may be writing only one part of a large set of documentation. You and your colleagues may have to produce documentation that has a single voice and style. Agreeing on that voice and style and helping each other maintain it may be part of your job. Therefore, skills in peer review – both giving and taking constructive criticism – may be important.
Following design templates and style standards
Many companies have set up templates for documentation, and you must tag your content to match the templates. For example, you might need to code each note, tip, or caution with a specific style so it shows up on screen or in print with the right font, size, and color.
Many companies also have a corporate style guide, which may cover everything from how to punctuate a bulleted list to whether “web site” is one word or two.
Templates and style standards can make your job easier because you don’t have to decide anew each time you write. On the other hand, if the templates don’t work for you, you’ll have to negotiate with the owners of the templates and style standards to make changes. If you work for a startup, most likely you will be defining the templates, style, and publishing formats yourself.
Working with reviewers
In addition to getting information from engineers, you need good negotiating skills to work well with editors and with technical, managerial, and sometimes legal reviewers. After preparing a draft of your documentation, you submit it to engineers to review it for accuracy. Then you submit it to product managers to look to review the messaging. You may then submit it to a team editor who checks your content against a company style guide. Finally, legal groups will sometimes look for intellectual property rights surrounding images or code libraries you’re using.
Meeting regulatory standards
One challenge in some industries and locations is complying with regulatory standards for your content. In manufacturing engineering jobs in Germany, for example, your documentation might need to comply with specific regulations required by governing standards boards. These standards ensure that the documentation leads to safe operation of the equipment or includes proper documentation of risks. The financial and medical sectors also require compliance with regulatory standards.
Learning new tools
Many job descriptions for technical writers focus more on tools and technical knowledge than on skills such as thinking clearly, organizing information well, and writing in a user-centered style.
As you read descriptions of jobs you are interested in, you may find that you need to learn and practice particular tools to make yourself a good candidate for those jobs. Currently, the number of authoring tools in the tech comm space is diverse and fragmented, with no tool being predominant among technical writers. By learning a few tools, however, you can demonstrate enough technical competence to convince employers that you can learn other tools.
Ideal training
A bachelor’s degree is all that is required. A master’s degree can be helpful in expanding your capacity to organize and manage complex information, but it is not required.
Many colleges and universities offer programs in technical communication. The Society for Technical Communication (STC – the technical writers’ professional organization) lists more than 170 programs leading to a Bachelor of Arts or a Bachelor of Science degree. If you are first considering college, you might want to look into the Academic Database at www.stc.org.
However, you don’t have to earn a degree specifically in technical communication. In fact, many technical writers fall into technical writing from a variety of other backgrounds. Engineering backgrounds (especially computer science) provide strong foundations for technical writing. If you have solid writing skills in addition to technical depth, this provides a knockout combination in the job market.
If you have a humanities background and want to put your writing skills to work in a technical context, you can also have a lot of success. You can often learn the technical information on your own, depending on what you’re documenting.
If you’re starting out in college, an ideal focus could be to double major in computer science and English. Most of the jobs for technical writing in the United States are in software, and the API documentation space is especially hot. (An API, or “application programming interface,” allows different systems to interact with each other, sharing data and performing other functions.)
Other helpful degrees (besides English and engineering) would be a focus on graphics and design, digital media, or library science. If you want to go into medical or life sciences writing, get a degree in a related biology or chemistry field.
Many colleges also offer a certificate program for people who are transitioning into a career as a technical writer. These programs are usually geared to working professionals, offering classes online or in the evenings and focusing on practical skills.
Regardless of your formal training, you can learn along the way as discussed in Chapter 3 to overcome hurdles in technical knowledge.
Potential job titles
Most jobs in technical communication will use the title “Technical Writer.”
However, technical writers often prefer titles that give more emphasis and credit to the many non-writing tasks they do, such as:
- Information Developer
- Knowledge Engineer
- Technical Communicator
- User Assistance Professional
Career pathways that may be combined with technical communication in job descriptions:
- Content writing/Information design
- Content strategy
Get more online: uxcareershandbook.com/technical-communication
Again, you order the UX Careers Handbook from Amazon here.
Special thanks to Ginny Redish for her edits in my section and in the book overall.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.