Features

How to Research What You Need to Learn to Be Successful as a Technical Writer

By Tom Johnson

Keeping up with Technology

Some years ago, I had an informal chat with other tech writers on my blog about the biggest challenges in their work. The prevailing theme in their responses involved keeping up with technology. Various writers explained:

  • “I have trouble keeping up with the rapid pace of innovation in the IT world and the many ways to deliver content.”
  • “For me, it’s keeping up with the right technology and fighting to increase productivity without making our jobs horrid.”
  • “Part of the problem about keeping pace with technology is that we often work under tight deadlines. … at the end of the day, to learn new tools and technology, it’s often on your own time.”

The recurring theme was keeping up with everything you needed to know to be successful. That chat took place a decade ago, in 2007 (See Johnson 2007).

The Exponential Curve of Information

Looking back, those seemed like the early days of the Internet, when all you needed to know was HTML, a little CSS, and a couple of help authoring tools to get by. Now the number of proliferating technologies seems to be growing at an exponential rate.

In “How it feels to learn JavaScript in 2016,” Jose Aguinaga explains that jQuery, Bootstrap, and Bower are now passé. Aguinaga says today front-end Web developers have replaced those libraries with React, JSX, Babel, ES6, Browserify, WebPack, VueJS, RxJS, Grunt, Gulp, Broccoli, SystemJS, Typescript, OCaml, Ramda, Fetch, Request, Bluebird, Axios, Flux, Flummox, Alt, Fluxible, Redux, SystemJS, and dozens more JS frameworks and tools.

Continuing Education Efforts

To help their employees keep up with the needed research and learning to stay current, many companies provide continuing education for their employees and encourage employees to regularly update their technical skillsets. AT&T chief executive Randall Stephenson says, “People who do not spend five to 10 hours a week in online learning will obsolete themselves with the technology” (Hardy 2016).

This isn’t just fear in the face of the technology unknown. According to TechCrunch, a study by Washington University claims that 40 percent of companies in the Fortune 500 will be gone in 10 years. This is because technology advances at such a rapid rate, if employees don’t keep up, their skill sets will become outdated—and in turn so will the products they create.

Research as a Strategy

Keeping up isn’t just a matter of amplifying your learning time. You can’t just hunker down and spend all day reading one technology book after another. Few have the time, patience, or even interest for that. Instead, you have to be discerning in what you learn. You have to research out what is truly worth learning that is relevant and helpful to your larger role as a technical writer in producing documentation.

This element of research—looking in multiple domains that include product, technology, user, and industry information, and narrowing the information by user tasks—is the strategy that will help you become successful in the face of endless information.

What to Research and Why

The knowledge a technical writer needs to research can be divided into at least four main groups:

  • Product knowledge: Information about the product you’re documenting—how it works, how it’s configured, what features it provides, and so on.
  • Technical knowledge: Technical information required to use the product, such as an understanding of a programming language or platform (Java, Android, PHP, and so on).
  • User knowledge: Information about the goals, tasks, questions, issues, complaints, requests, and other feedback from the people using the product.
  • Industry knowledge: Information about the general trends, issues, and other topics in the business context in which the product lives.

Unless you have a lot of time on your hands, you won’t have the bandwidth to master each of these knowledge domains. You have to use discerning research to limit the scope. Mark Baker proposes looking at user tasks as a way of restricting the research you need to do in each domain. He writes:

You clearly can’t master all of these four fields [technology, product, and industry knowledge], so you need some way of limiting what you need to know about each of them to be effective. The task is what we write about, so the task is what we need to know (See Johnson 2016).

In other words, you can filter down these knowledge domains by looking at a specific user goal or task.

Research by Academics Versus Research by Industry Practitioners

Here I want to pause and explain how research done by academics differs from research by industry practitioners. When academics do research, they often start with a question and gather data through participants in a formal study or experiment. They analyze the results using rigorous methods to identify errors and faulty assumptions. Typically, their goal is to add to the body of knowledge, so academics carefully explain the methodology they used in gathering data and the formulas in their analysis. If the data and methods are valid, the conclusions will more likely be accepted.

For industry practitioners, their research is broader and less focused around a particular study or experiment. Practitioners gather information from various domains to inform the documentation they’re writing. Practitioners drink from a firehose of information to pull out relevant nuggets that will shape needed tasks and other details in their docs. The practitioner looks for information that will influence the business goals that drive product usage, trends in technologies and skillsets among user demographics, and ways to help increase product adoption and dominance in the marketplace. Practitioners care little about rigorous methodology or quantitative analysis—they’re just trying to stay abreast of what’s going on with their product, the users, and the industry so they can create better documentation.

In both cases, research—the gathering or discovery of information about a subject—is being done. Industry practitioners don’t often label their information gathering as “research”, but they are in fact doing research. I prefer the term research over simply “learning” or “information gathering” because research implies something more. You’re not just absorbing or collecting new material; you’re skillfully navigating domains to determine what to learn, looking through vast quantities of information to decide what will be most useful, and how. It is this element of discernment amid a high wall of potential learning material that becomes key to succeeding in the practitioner role.

Example of Filtering Knowledge

I’ll clarify how the research process works for industry practitioners by going through an example of how I do research at my work. I document how third-party developers can create streaming media apps for Amazon’s Fire TV. (Fire TV is a set-top box similar to Roku or Apple TV—it converts a “dumb TV” into a “smart TV” by providing an online interface to Internet video apps and games). How would focusing on this general task—building streaming media apps for Fire TV—help limit the four domains of knowledge that a technical writer pursues? Let’s step through it domain by domain.

Product research: To research product knowledge, you, as a technical writer, would look at what frameworks are used to build streaming media apps. There are several frameworks (or starter kits) for building Fire TV apps. How do these starter kits or frameworks work? Can you set the frameworks up and make them work with sample feeds? How do users configure their media feeds and other navigation details? How do users adjust the appearance and other elements of their apps?

You probably spend the majority of your time researching this knowledge domain. To do the research, you immerse yourself in the product you’re documenting. You read wiki pages related to the project, set up meetings with engineers, and go to sprints for the relevant teams. You ask engineers for sample apps along with demos, and then you play with the product, using as real a scenario as you can, until you know the product well.

Technical research: You also research the technology behind the product. In this scenario, you study the technologies used in building streaming media apps. Android is frequently used for building apps for Fire TV, but the world of Android is almost as vast as Java. Saying that one needs to learn Android is like saying one needs to learn “medicine” or “databases.” Which part of Android do you learn? Again, you can filter the domain by looking at the user task.

Most of Android is actually focused on building apps for smartphones and tablets, not TVs. But your users will be building TV apps, so already you’ve whittled down the massive Android landscape.

Building TV apps involves understanding requirements for the “ten-foot experience.” To get the technical knowledge, you could read a book on Android in Safari Books Online or take a course on Android on Lynda.com. You could dive deep with a course on Udacity, watch videos on YouTube, or read general tutorials across the Internet.

The goal in acquiring technical knowledge is to become familiar with concepts and lingo to understand what’s going on at a high level. You don’t need to get lost in the technical details. You won’t be diving as deep as engineers do—they’re building production-ready apps from the ground up. (Diving too deep into the technology might actually exhaust all your other knowledge-gathering bandwidth.) But you need to learn enough to be technically competent with the product. This technical foundation is usually more difficult in developer documentation environments.

User research: It’s important to research what goes through the heads of users—specifically, what information do users who want to build streaming media apps need to know? What questions will they have? What issues or feedback have you received so far from existing users?

When I look at user feedback (from forums, submitted apps, contact forms, etc.), it turns out most developers don’t want to build Fire TV apps from scratch. They already have an Android app they built for Google and want to port it to Fire TV. What they need to know is how Fire TV differs from Android TV. How do they change their existing Google Android app to make it work on Fire TV? What Amazon APIs do they need to use instead to handle services such as in-app billing or maps? Again, user tasks have filtered the scope of the knowledge domain.

To get user knowledge, you can visit forums, send surveys, and talk with field engineers. You can pick the brains of product managers, check support logs, or look at search queries in metrics. You can attend user conferences, make visits to user sites, and more. Almost any place users go online, you can go, too.

Researching user information helps shape and inform your documentation efforts. Without this information, you might spend much of your time focused on acquiring and publishing the wrong information.

Industry research: Finally, technical writers need an awareness of industry knowledge. What’s going on with streaming media apps in the industry? What other starter kits and frameworks are available on other platforms? For example, how does the Fire TV app compare with apps for Apple TV, Roku, and Chromecast? Are there certain features or specs to be aware of across these different platforms? What trends are happening with streaming media apps on set-top boxes?

For example, if 4k is a common need, what do developers need to know to make their videos play 4K? The Fire TV stick sells more than the Fire TV set-top box, but the stick’s CPU and chipset aren’t as fast. How does this business trend toward less performant but cheaper devices affect how developers code apps? Is there still a trend toward gaming with these (slow-CPU) devices? What will Apple release in their upcoming version of Apple TV? Is HDR (high-definition range) going to be the next big must-have feature?

You get this knowledge from researching industry information through websites, magazines, blogs, conferences, and other general news sources. Researching these industry trends and directions will help you focus your documentation in relevant ways.

Where Do You Find the Time?

Now that I’ve covered the types of information a technical writer needs to research, another question remains. How do you find the time to get this knowledge? Even if you filter the product domains by user tasks, there is still a lot of ground to cover.

Here’s my approach. I tackle the product, user, and industry knowledge at more or less the same time. First, I compile a list of relevant news sources to gather the information. The links include the following groups:

  • Wiki pages (including change histories, which highlight active pages and topics)
  • Code repositories (specifically commit messages from relevant engineers)
  • Blogs (corporate blogs, marketing blogs, product evangelist blogs, internal blogs, and industry blogs)
  • Email distribution lists (some information is only sent in email)
  • Support channels (forums, Stack Overflow, incident logs)
  • Issue tracking sites like JIRA (sprint charts, recently updated items)

My list of links has about 25 different information sources. When I roll into work in the morning, I spend about 30 minutes checking all these new sources. I usually don’t read each item thoroughly, but instead I start by skimming titles and headings to look for new information.

Then, when I find some relevant nugget, I log a task item (in JIRA) to add the information to the documentation. This research session works well and makes me feel aware of what’s going on.

Usually, one source will have more information on some days than others. For example, a company blog post might have new case studies and videos that outline top tips or concerns from developers. Another day, an updated wiki page might reveal details about an upcoming feature and launch schedule. Another day, newly published apps in the Appstore might show a trend with a niche developer audience.

During my research session, I don’t spend time creating new documentation. Here I’m just gathering information and logging JIRA items. When it comes time to work on the tasks (JIRA items), I identify the top one or two JIRA items to focus on for the day. I drag these items into the “In Progress” column on my Kanban board.

Here’s where my deep-dive into technology comes into play. To address a JIRA item, I may have to spend some time learning about a concept. For example, if the JIRA is to address audio focus handling in streaming media apps, I could turn to YouTube. YouTube has many Google I/O presentations, including some that address audio focus. The YouTube video might introduce concepts that would be familiar to existing Android developers but which are new to me. To better understand these new concepts, I turn to my other resources for learning, such as Lynda.com, Udacity, Safari Books Online, or other sources.

Focusing in the Right Direction

As long as I’ve grounded the knowledge need in an actually relevant JIRA I’m working on, based on my research, I won’t feel like I’m learning the wrong thing. This is the problem with most tech courses and e-learning. You often spend time researching subjects that aren’t immediately relevant to your projects.

When you’re a working professional, you can’t sink countless hours of time in directions that seem like tangents. The effort must directly address the knowledge you want to gain. What you learn has to relate to JIRAs you’re working on—otherwise, the efforts become tangential and unproductive.

The research you do informs the learning angles you pursue. Sometimes I hear people tell me they want to ramp up their technical skills, so they take a class in iOS programming, AWS architecture, or AI, but these technical skills usually have little to do with their current roles or documentation projects.

Although there’s certainly merit in learning for learning’s sake, and I applaud the effort, it might not be sustainable in the long run. As an industry practitioner, your research efforts have to pay dividends in the documentation you write. The technology landscape is wide and vast in what you could potentially learn. If you don’t do the necessary research to inform what is actually relevant to your documentation tasks, you’ll find yourself taking many leisurely strolls down technology lanes that don’t get you closer to your destination. That destination, for technical writers, is to produce great documentation for users.

Conclusion

Researching knowledge domains and then acting on the knowledge is a challenge that crosses all disciplines, but it’s especially relevant to practitioners in technology fields. Focus your research on the four main domains—product knowledge, technology knowledge, user knowledge, and industry knowledge. Then limit your scope to the user’s tasks that you need to document. This will help you both learn what you need to know to write great documentation and have a successful, long career.

References

Aguinaga, J. 2016, 3 Oct. How it feels to learn JavaScript in 2016. Hackernoon. Retrieved from https://hackernoon.com/how-it-feels-to-learn-javascript-in-2016-d3a717dd577f.

Hardy, Q. 2016, 14 Feb. Gearing up for the cloud, AT&T tells its workers: Adapt, or else. The New York Times. Retrieved from https://www.nytimes.com/2016/02/14/technology/gearing-up-for-the-cloud-att-tells-its-workers-adapt-or-else.html.

Johnson, T. 2007, 1 Mar. Number one issue for technical writers today: Keeping pace with rapidly evolving technology. idratherbewriting.com. Retrieved from http://idratherbewriting.com/2007/03/01/number-one-issue-for-technical-writers-today-keeping-pace-with-rapidly-evolving-technology/.

Johnson, T. 2016, 27 Apr. Three types of knowledge every technical writer needs to be successful. idratherbewriting.com. Retrieved from http://idratherbewriting.com/2016/04/27/triangle-for-tech-comm/#comment-2649234858.

Mehta, K. 2016, 30 Oct. In a knowledge economy, corporate learning is necessary to survive. TechCrunch. Retrieved from https://techcrunch.com/2016/10/30/in-a-knowledge-economy-corporate-learning-is-necessary-to-survive/.

TOM JOHNSON (tom@idratherbewriting.com) works as a technical writer for Amazon in Sunnyvale, California. He writes a blog called idratherbewriting.com and is working on a book about API documentation.