Tech comm trends -- why tech writers will be collaborating more with engineers

by Tom Johnson on Oct 9, 2018
categories: api-doc • simplifying-complexity • writing • academics-and-practitioners

• Note about this revision
• Why trends intrigue me
• The impact of UX and the need for documentation
• Evaluating trends based on tech comm job data
• An “evolution” of roles, but evolving towards what?
• Looking at job advertisements to extrapolate the evolution of tech comm
• Technical knowledge valued more than writing skills
• More complexity in technology is driving the valuation of technical knowledge
• Trying in vain to keep up with the pace of technology
• Technical knowledge is essential to writing
• Embracing a more collaborative role in authoring specialized content
• Conclusion
• Your reactions and input
• Slides
• References

Note about this revision

Last week I published a 7-part series called Tech comm trends: Providing value as a generalist in a sea of specialists. However, I felt that the essay series (and its accompanying presentation) were trying to cover too much ground. I was not only identifying trends but also trying to argue for strategies to address gaps that the trends created. The approach felt like it lacked coherence and focus. As a result, I decided to limit the scope to just the first part: trends. I realize this means cutting out about half the essay/presentation, but I think it has more punch this way.

In this post, I’ve expanded the section on trends with more depth, analysis, and information. I’ve also incorporated the feedback I received from the survey on the previous version (thanks to all who participated and responded).

At the bottom of this post (in Your reactions and input), I also have some survey questions to gather your level of agreement or disagreement. Your responses help me better align my observations. Thanks!

Why trends intrigue me

Posts about trends usually receive a lot of views and comments, which suggests that trends are an important topic for tech comm professionals. Why are trends important to recognize and follow? In a rapidly changing field like technology, almost everything is in constant flux. Sometimes you wake up and so much seems to have changed.

Consider how some previously dominant companies simply vanished: Blackberry, Blockbuster, Borders Books, Toys ‘R’ Us, Kodak, Radio Shack, Tower Records, Circuit City, Encyclopedia Britannica, and others. Some scholars say the reason these companies went bankrupt is that they focused only on what helped make them successful and became blind to further innovation. They also focused too much on the market today rather than the one forming tomorrow (see Companies That Went Bankrupt From Innovation Lag).

These are companies, of course, not job roles or functions. But I think the same might be same of technical writing professions. How do we stay marketable in this constantly changing field? We have to focus on trends if we want to take strategic steps to stay in business tomorrow. We don’t want to wake up one day, perhaps after being laid off and unable to find new work, and ask in a surprised, perplexed way, “What happened?” We want to avoid being caught off guard in becoming professionally unmarketable.

But discerning trends is not an easy task, especially if you want to support your assertions with data and more evidence than simply guessing based on the latest shiny technologies. I’ll do my best in the sections that follow to ground my assertions in data.

In a nutshell, my argument is that technology seems to be getting more specialized and complex. This trend toward specialization and complexity has ratcheted up the value of technical knowledge, making it more sought-after than writing skills. The increased level of complexity requires technical writers to collaborate more with engineers in the authoring of content. In a way, this collaboration is the specialization of the authoring process itself — dividing the content development more to engineering and the information usability more to language specialists. To drive up their value in organizations, technical writers should look for ways to collaborate more skillfully with engineers in creating content.

The impact of UX and the need for documentation

We need a starting point for this discussion, so let’s begin by analyzing the impact of UX design on tech comm. In a recent episode of the Cherryleaf podcast, 40. The evolution of the technical communicator’s career, Ellis Pratt discusses an article called Software technical writing is a dying career (but here’s what writers can do to stay in the software game), by Jim Grey published in 2015.

Grey’s main argument is that “companies are leaning into good user-interface design and stepping away from online Help systems and printed/PDF documentation.” Grey explains that he had lunch with a business owner who explained this transition, saying:

Technical writing is dying off…. It’s all about clean, engaging UX now. I have talked to more than a hundred startup and small software companies as I’ve built my business. Almost none of them have technical writers, and almost all of them have UX designers.

Grey argues that UX design has displaced the need for tech comm in software companies. Instead of hiring a tech writer to provide explanations for confusing interfaces, companies hire UX designers to get the design intuitive from the start.

Keep in mind this was a simple blog post. Grey has noted that he “wasn’t trying to write a well-researched article for the ages,” and it’s not fair to make him the poster child of this argument. This idea has been bandied about by lots of people in a variety of contexts — I just chose this reference to make the idea more concrete. (Grey explained in a note to me, “I was just trying to make a point that old, traditional, explain-the-UI tech writing appeared to me to be going away, but that a technical communicator can stay employed by pivoting into some related fields.”)

Even it was only a simple blog post, Grey stood by his argument. Sensing his irrelevance as a technical writer, Grey jumped off the documentation ship and into software testing instead, where he says he brought along many useful skills he learned as a technical writer.

Let’s talk about the influence of UX on tech comm. Are companies prioritizing UX design over tech comm in companies? Undeniably, the practice of user experience design has matured into a full-fledged discipline rich with research-backed design principles, methodology, and professional expertise. UX designers are now much more common in engineering groups. Companies recognize that usable interfaces can make the difference between product success and failure. Companies like Apple have cemented the idea that users are willing to pay for well-designed products that don’t rely on a lot of documentation.

UX has championed this emphasis on the user experience. But does it mean companies are eliminating tech writers from their organizations?

Not necessarily. Some commenters in a previous survey noted that many UX designers see good copywriting as part of UX and will often champion the inclusion of technical writers in the design process. One respondent noted:

Effective writing that makes processes simple to follow is one part of good UX, not separate. Unless UX design roles demand writing skills, I don’t expect technical writing roles to disappear. In the last five years, UX designers have probably been more effective at advocating for their discipline and inserting themselves within developer-led discussions than technical writers have.

In other words, rather than remove writers from the equation, UX designers become advocates of good writing, increasing the involvement of tech writers in UX (especially when designers lack writing skills themselves). For some tech writers, their primary role is, in fact, “UX copywriting.” For others, UX writing is just one aspect of their role among many other types of work.

The latter is true for me. I occasionally work with a design team in my current role. They create design mocks, and they ask me to review the text. I provide detailed feedback that covers every aspect of text in the UI, from button labels to microcopy, dialog box text, error messages, and more.

However, I don’t do a lot of UX copywriting (maybe once a month), since we have a small design team and they don’t crank out new user interfaces too often. But without the UX team, I’m not sure I would be regularly included in these UI writing efforts. In this case, UX has increased my role rather than taken it away.

On the other hand, without the UX design team, I’m sure the user interface that the engineers (without UX skills) might create would be so bad that I’d be called in with great urgency to provide more detailed explanations, even video tutorials walking users through the confusing process. So whether UX has a positive or negative influence on my need within teams is somewhat uncertain to me.

Evaluating trends based on tech comm job data

Was Grey right or wrong? So far, I haven’t presented any data. It’s easy to trade anecdote for anecdote, but what does the data say about tech comm jobs? Are they diminishing? If so, why? Let’s dive into some data from the Bureau of Labor Statistics (BLS).

If you look at the latest STC Salary Database (based on BLS data), you can see that tech writing jobs have actually grown by about 3,620 jobs in 4 years:

Overall, in 2016, there were about 50,000 technical writing jobs in the United States. The report notes that technical writing is “the only occupation [among professional writing disciplines] which has seen employment growth in each year since 2011, with an average annual employment increase of 1.9%.”

Despite the growth, technical writing jobs aren’t necessarily keeping pace with software development jobs. The BLS says the job growth for software developers from 2016 to 2026 is projected at 24%, but for technical writers, the job growth is projected at just 11%. (Both growth rates are higher than the national average, which is 7%.)

To put these numbers into perspective, suppose 10 technical writers support 1,000 engineers. In 2026, 11 technical writers will support 1,240 engineers. If the rate stays the same for the next decade, in 2036, 12 technical writers will support 1,538 engineers.

So yeah, while technical writing jobs might not be diminishing, they are shrinking proportionally. But as far as measuring the impact of UX or other causes affecting the job growth, the BLS has little to say except this:

Employment growth will be driven by the continuing expansion of scientific and technical products. An increase in Web-based product support should also increase demand for technical writers. Job opportunities, especially for applicants with technical skills, are expected to be good.

This last point — “especially for applicants with technical skills” — is something I’ll return to later since there has been a continual requirement for subject-matter familiarity in job advertisements.

An “evolution” of roles, but evolving towards what?

What does Pratt make of Grey’s blog post? In the podcast, Pratt looks generally at job trends and decides that no, technical writing jobs haven’t gone away. Pratt’s company, Cherryleaf, is primarily a recruiting agency for technical writers, so the mere fact that he’s still in business suggests that companies are still seeking technical writers.

But Pratt does make another point. He says:

Is this true? Has the tech writing job disappeared since 2015? Clearly not, because there are still … [many] technical writers and authors. But I think there is a truth in saying that the role of the technical author is changing, and the requirements and the skills that they need are changing as well. And it may be that the job title changes and the way in which the role is perceived.

In other words, he says the jobs haven’t disappeared, but the roles, requirements, and skills have evolved. In a survey in a previous post, I asked readers to agree or disagree with this statement:

Technical writing jobs haven’t diminished, but the profession is evolving.

Of the 65 respondents, about 53% of readers agree and 39% strongly agree with this statement (for a total of 92% agreement). But beyond the general role, requirements, and skills, exactly what is evolving in tech comm? Are we changing in positive ways to align with tomorrow’s needs? More importantly, what kind of data supports this assertion about the evolution of the profession? We need to get much more specific here if our analysis of trends will be useful.

Looking at job advertisements to extrapolate the evolution of tech comm

To get a better picture of the role, requirements, and skills in demand, let’s turn to some research based on an analysis of job advertisements. In “The Evolution of Technical Communication: An Analysis of Industry Job Postings” (Nov 2015 Technical Communication Journal), Eva Brumberger and Claire Lauer make an astute observation about determining trends. They say that by looking for patterns in job advertisements, you can see what employers are looking for and hence learn what skills and needs are trending in the industry. They write:

Job advertisements, as a genre, have the specific purpose of hiring an employee for a company or organization, so they typically include consistent kinds of descriptive information that can serve as a barometer of industry trends when studied over years and even decades.

After analyzing about 1,000 job postings (which appeared during a 60-day period in late 2013), what did they find? Well, they found that the job ads painted a picture far more diverse than the BLS’s description of the technical writer occupation. The authors noted the incredible variety of roles and deliverables that tech comm professionals are engaged in.

However, part of this diversity is a result of their broad focus on job titles and categories. In their analysis, they included a variety of titles beyond “Technical Writer.” Some of the job titles included “Social Media Manager,” “Front End Developer,” “Web Content Analyst,” “UI Designer,” and more. They excluded job ads that focused exclusively on a technical tool or framework with no rhetorical role in communication. They also divided the job postings into five main categories: Content Developer/Manager, Grant/Proposal Writer, Medical Writer, Social Media Writer, and Technical Writer/Editor. Given this wide net they cast, it comes as little surprise that they would find tech comm professionals engaged in such a variety of work.

Although this wide scope is probably appropriate for a tech comm program, my world tends to focus mostly on technical writing (which could include software or hardware docs). So I’m going to narrow my focus on this “technical writer/editor” category in Brumberger and Lauer’s study.

Here are some quick highlights of what they found. 52% of their analyzed job ads fall within the technical writer/editor category. Within technical writer/editor jobs, 26% of the advertisements are for IT services/software, followed by 18% in professional and business services. The greatest job concentrations for technical writers/editors are on the east or west coast. About 85% of what technical writers/editors produce are user guides/tech docs, 13% web content, 13% video content or multimedia, and 19% reports.

The most sought-after professional competencies for technical writers/editors include written communication (75%), Editing (51%), Project planning/mgmt (49%), Visual communication (49%), Subject-matter familiarity (45%), Working with SMEs (41%), and Style guides/standards (40%). They note:

Overall, written communication continues to dominate the technical communication landscape, but our data emphasize that several additional professional competencies are also essential, most notably project management, editing, visual communication, research, and, as Lanier (2009) noted, subject matter familiarity.

Commenting on overall trends across the job categories, the researchers observe the need to push content across multiple channels while adhering to brand, and the need to build relationships with customers through content. In part, this study was done during the rise of social media, which pulled some of the focus of tech comm into marcom. However, in their data, only 3% of job advertisements for technical writers/editors indicate responsibilities for social media content, so I’m guessing that this larger comment relates more to the “Social Media Writer” category than the “Technical Writer/Editor” category. (That’s not to say I don’t think technical writers could engage in this multi-channel branding more fully, only that I’m not sure job advertisements for technical writers are asking for this skill.)

The authors deliberate about whether it’s a good idea to specialize with more subject matter familiarity. They say this familiarity is particularly relevant in technical writer/editor job categories. Given the broad range of skills, roles, and deliverables within the umbrella of technical communication, the authors say remaining a jack-of-all-trades generalist would give you a lot of mobility and versatility within the field, empowering you with capabilities in a lot of different roles and functions. However, they acknowledge that others see specialized knowledge as being more valuable. The authors explain the view from another research study:

Baehr (2015) [who studied perceptions of 8 tech comm managers] noted that this [specialization] was a point on which managerial perceptions varied; some participants felt that a broad skillset would “permit technical communicators to be more agile, adaptable, and flexible in their roles and to add greater value to organizations,” while others believed that specialization was “inevitable” (p. 116). Baehr concluded that the best course of action would be to develop multiple specializations, which would “enable technical communicators to define their own roles, to a certain extent” (p. 116). Our data suggest that there are several points of overlap in products and competencies, which could allow some degree of movement among job categories — or multiple specializations — if one maintains a broad skillset and flexible outlook.

In other words, the authors acknowledge that remaining a generalist would give you more mobility within the technical communication profession (given its variety), but they recommend multiple specializations as well, especially where the specializations might strategically overlap into multiple roles.

In this discussion about whether to specialize, some have pointed out the danger of specializing as well. If you decide to pour all your efforts into, say, learning Python, you might be well-suited for roles documenting Python-related APIs and SDKs, but beyond that, your skills will likely run shallow. In other words, you would be really qualified for the 3 Python documentation jobs but not so qualified for the 30 other technical writing roles that have nothing to do with Python and more that require knowledge of web metrics, information architecture, localization, and more.

What jumps out at me most in Brumberger and Lauer’s research is this discussion about “subject matter familiarity” (which is how specialized skills are described). If we compare a similar job advertisement analysis done seven years earlier by Clinton Lanier (“Analysis of the Skills Called for by Technical Communication Employers in Recruitment Postings”, published in February 2009 in Technical Communication Journal), can we see any trends with criteria for subject matter familiarity?

Lanier analyzed 327 job postings in 2006, limiting the scope to jobs with “technical writer” in the title and that required two years of experience or less only (which would thus be most suitable for graduating students to apply for). Regarding subject matter familiarity, Lanier found the following:

… 112 of the postings (34%) required or desired the potential writer to have experience writing about the specific subject matter that the current job involves. [For example], if the candidate was applying for a software documentation job in which they were going to be writing application programming interfaces (APIs) or online help, many of the positions required or desired that they have written such types of documents for the related types of subject matter.

In other words, employers have been seeking subject matter familiarity among job applicants in a consistent way since 2006. Even for job postings requiring just two years of experience or less (almost entry-level positions), 34% of employers want the candidate to have subject matter familiarity.

Lanier summarizes a respondent’s point of view in another academic article advocating specialization. Lanier explains:

This reflects the trend that technical communication is moving away from a “Jack of all trades” model, where technical writing is a very generalized concept, and toward a model that is more specialized and contextually defined. Giammona (2004) likewise found participants stating that new writers would benefit from experience within the industry they are going to write for, and Kim and Tolley (2004) related the story of a writer whose supervisor found the participant’s background in science more important than her knowledge of computing.

Given that Lanier restricts his data set to jobs requiring 2 years or less of experience, it’s hard to compare the data set with Brumberger and Lauer’s. However, 34% in 2006 and 45% in 2013 suggests a constant emphasis on specialized knowledge. Deciding to specialize in a particular engineering domain wouldn’t be considered a new trend, but its consistency for the past 15 years suggests that it’s an ongoing requirement — one that is possibly increasing as a criteria for jobs.

Technical knowledge valued more than writing skills

One of the surprising things Lanier found was that most job advertisements explicitly sought specialized skills more than they sought writing skills. Lanier explains:

… it was a bit surprising to see the low number of postings calling for these technical writing specific skills (17%). After reading the articles discussed above, my assumption was that the request for these skills would be present in a large majority of the postings, but this was not the case. Again there seems to be a trend by employers to want specialized skills, evident by the larger number of postings asking for familiarity with the specific types of documents they work with (24%).

In other words, the job advertisements had a surprisingly low number of requests for technical writing specific skills (just 17%); instead, they focused more on the need for specialized knowledge skills (24%).

Imagine for a moment that you’re a hiring manager. You have two candidates for a tech writing position: a former engineer who has a strong technical background but little writing experience, and an experienced writer who has a veteran track record and extensive portfolio but is new to the technology domain for the project. Who do you hire?

When I’ve been in situations like this, I’ve seen hiring managers choose the one with stronger technical skills and weaker writing skills every time. As long as the writing isn’t red-flag poor, hiring managers are willing to overlook more advanced writing skills.

This experience (and Lanier’s research) points to a larger trend toward the devaluation of writing. Having “writing skills” doesn’t seem to resonate much anymore because, presumably, everyone can write — or at least write well enough to get the job passably done. What’s important is technical acumen and subject matter familiarity, not stylistic flair. So you hire the candidate with an engineering background and address any style issues with an editorial pass — because it’s easier to teach writing than technical skills, some say.

In my recent blog post, If writing is no longer a marketable skill, what is?, I noted (after comparing web metrics) that writing skills don’t seem to sell in the job market, so you have to supplement writing skills with some kind of hybridization to make them seem valuable. I took a poll on my site to see which hybrid job titles were most common, and out of 277 respondents, the top roles were as follows:

• Technical writer/editor (14%)
• Technical writer/content strategist (7%)
• Technical writer/information architect (7%)
• Technical writer/project manager (7%)
• Technical writer/information designer (6%)
• Technical writer/content developer (7%)
• Technical writer/API docs specialist (5%)
• Technical writer/doc tools guru (5%)
• Technical writer/usability specialist (4%)
• Technical writer/UX copywriter (3%)
• Technical writer/video producer (3%)
• Technical writer/DITA specialist (3%)

Of course, these dual roles are self-defined only. In the HR books, one is usually still classified as a “technical writer,” but that’s not how we promote ourselves.

One of the early trends to carve the intellectual heart out of technical writing was the content strategy movement. When content strategy became a common term, it deflated the intellectual and analytical foundations of technical writing, reducing the act of writing to mere wordsmithing.

The discussion about whether writing involves intellectual and analytical thought has been going on in other disciplines as well, such as in academia. Writing is rarely allowed to be its own discipline but is rather a complementary skill for other knowledge-oriented fields such as Engineering. Robert Johnson, a professor of writing, counter-argues by noting that from the earliest days of the Greeks, the true artist had to consider the end goals of their art. Johnson explains,

… techne and the arts of making have two ends (telos). The initial end is the thing being produced, the product. Beyond the product, however, is the use (or uses) for the product. (Craft Knowledge: Of Disciplinarity in Writing Studies)

In other words, a writer (or artist or craftsperson) isn’t merely a word technician — someone who understands grammar and style and nothing more. A writer considers the end goal of the content and develops strategies designed to achieve those ends. Achieving the end goal very commonly involves acquiring, analyzing, digesting, and articulating technical knowledge and information. Subject matter familiarity is a necessary component for achieving the ends of discourse.

And yet, that’s not how people perceive writing anymore. Writing is merely wordsmithing of content. The development of the ideas and knowledge behind the content is … another function.

More complexity in technology is driving the valuation of technical knowledge

What exactly is driving the emphasis on technical knowledge over writing skills? If you consider an analogy from economics, technical knowledge is becoming more prized because it is becoming a scarce commodity. And it is becoming a scarce commodity because technology is getting more complex and specialized. It is the law of supply and demand at work in the enterprise, applied to knowledge. When very few people have knowledge of X, your possession of X knowledge can make you highly valued (assuming people care about X).

Some will object that technical writers are specialists, but of another kind of knowledge. As a technical writer, you’re a specialist in language simplification, clarity, information usability, publishing, and user analysis. But is this type of knowledge special enough? Is it valued enough in the enterprise? Perhaps not. People seem to get by with simple tools like wikis and Microsoft Word, but they can’t get by without the raw technical content.

Because the technology landscape itself is becoming more complex and specialized, it is driving up the value of technical knowledge.

How do we know if technology is getting more complex? In Implications of Tech Stack Complexity for Executives, the authors explain that one reason the technology landscape has shifted towards greater complexity is due to a transition away from single vendor systems. The authors explain:

Not too many years ago, before social media, mobility, the Internet of Things (IoT), cloud, and big data muddied the field, technology stacks (the different layers of technology required to implement an application) were simpler and often vendor-specific. A good example is the Microsoft stack: .NET languages for programming, IIS as a web and application server, and the SQL Server database.

Today, technology stacks have exploded. We have platforms such as Microsoft Nano Server, Deis, Fastly, Apache Spark and Kubernetes. New tools pop up every week including Docker Toolbox, Gitrob, Polly, Prometheus and Sleepy Puppy. Programming languages and new frameworks such as Nancy, Axon, Frege, and Traveling Ruby are introduced. Advanced techniques such as the Data Lake, Gitflow, Flux and NoPSD mature. This list goes on and on.

They depict the change as follows:

For companies to develop world-class software, the authors explain, finding the IT talent to develop these sophisticated solutions can be a real challenge. The authors say that “not only has the breadth of skills increased, but the depth of skill required (advanced versus basic) has increased also.” And given how quickly technologies are changing, you also need people who aren’t just locked in the present but who will “quickly acquire” tomorrow’s technologies as well.

In Overcomplicated: Technology at the Limits of Comprehension, Samuel Arbesman also expands on the trend away from single solution systems to multiple system solutions. Arbesman talks about how we’ve built systems that very few people fully understand, and these systems are interacting with other systems (often through APIs) in ways no one can fully predict. Sometimes when these complex systems have bugs (such as with Toyota’s acceleration problem), we end up scrambling through millions of lines of code across many different systems, trying in vain to find the problem.

Again, what’s the end result of this increased complexity? In software development contexts, technical knowledge is increasing in its value while generalist skills like writing are decreasing in value.

In a comical article called How it feels to learn JavaScript in 2016, Jose Aguinaga contrasts what it’s like to learn JavaScript today versus a number of years ago. His format is an imagined conversation between a newbie and advanced frontend developer. Here’s a quick excerpt:

I need to create a page that displays the latest activity from the users, so I just need to get the data from the REST endpoint and display it in some sort of filterable table, and update it if anything changes in the server. I was thinking maybe using jQuery to fetch and display the data?

-Oh my god no, no one uses jQuery anymore. You should try learning React, it’s 2016.

Oh, OK. What’s React?

-It’s a super cool library made by some guys at Facebook, it really brings control and performance to your application, by allowing you to handle any view changes very easily.

That sounds neat. Can I use React to display data from the server?

-Yeah, but first you need to add React and React DOM as a library in your webpage….

Aguinaga goes on to explain about 30 confusing JavaScript frameworks and technologies that frontend developers need to sort through when coding, including 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.

Aguinaga’s article illustrates how, for the past few decades (at least behind the scenes in the realm of development), technology has been getting more and more complex and specialized — more extensive, varied, complicated, and deep. The engineer who implements the frontend of a site has a very different skill set from the one working on the backend.

For contrast, think back to a time when we had “webmasters.” The idea of a “webmaster” — a person who handles all aspects of a website — is an especially dated idea. Specialization has permeated all aspects of technology organizations. Today, you’re not just a “software developer.” You’re a JavaScript developer for web apps, you’re an Oracle database specialist, you’re a release management configuration engineer, and so on.

We have these specialists because complexity has increased. An article in the Harvard Business Review noted that we’ve even moved past specialization into “Hyperspecialization.” The authors explain,

Just as people in the early days of industrialization saw single jobs (such as a pin maker’s) transformed into many jobs (Adam Smith observed 18 separate steps in a pin factory), we will now see knowledge-worker jobs — salesperson, secretary, engineer — atomize into complex networks of people all over the world performing highly specialized tasks. (The Big Idea: The Age of Hyperspecialization)

The author notes that with some encyclopedia articles, even different paragraphs within the same article are sometimes written by different specialists. Each specialist-written paragraph fits together into a larger article.

Some might object that technology is getting simpler for users, which makes the job of technical writers easier because we write for users who are the recipients of these simpler UIs.

The level of complexity depends on your audience, but generally technical writers are pulled towards scenarios of complexity rather than simplicity. You might be writing for internal engineers, engineers in other companies, or other professionals that aren’t engineers or end-users but somewhere else along the technology spectrum.

And for sure, some user interfaces are getting simpler (thanks UX designers!), but the code behind them is also getting more complex. The classic example of this shift towards simple frontends and complex backends is Google’s homepage. On the surface, it looks pretty simple. But go to View > Source and copy the code on that page, and then paste it into Microsoft Word. It’s 73 pages long!

Explaining available search parameters might be easy, but explaining the SEO algorithm behind the search is surely complex. The level of difficulty depends on who you’re writing for.

Consider another example: voice interaction. When I say to my Fire TV, “Alexa, show me the latest action movies,” this natural language interface attempts to simplify the user experience. There’s no need to find the right menu, to type out my search using the remote controller’s direction pad, and so on. End-users can just use their natural language.

But behind the scenes, making this simple language interaction has an incredible amount of complexity and code. There are multiple systems interacting in harmony with each other — or sometimes clashing, which can result in Alexa misinterpreting your utterance and returning something unexpected.

Technology is like an iceberg — seemingly simple on the surface for end-users, but with massive amounts of code underneath.

Trying in vain to keep up with the pace of technology

Looking at diagrams like those in the previous section strikes a bit of terror inside me because I realize how challenging it is to stay current in the evolving, deepening technology landscape. If you blink, you miss a new technology, and before you know it, your lack of understanding (what’s “blockchain” again, or “containers”?) has dated you.

In surveys I’ve done in the past, keeping up with the latest technology is one of the primary challenges for technical writers. About a decade ago (in 2007), I had a virtual chat with a group of tech writers to find out what their most pressing challenges were. Their answers (remember, this was 11 years ago in 2007) included the following:

• “For me, it’s keeping up with the right technology and fighting to increase productivity without making our jobs horrid.”
• “I have trouble keeping up with the rapid pace of innovation in the IT world and the many ways to deliver content.”
• “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.”
• “I agree and I’m willing to learn about new tools and technology. The question is, where to start, what’s the right thing to get into? What do I recommend that the company invest in?”
• “Another problem with keeping pace with technology is the sheer variety of languages, systems, tools, concepts, etc. There is so much to know. One can’t know it all. But I think we have to be savvy enough to learn what we need to know at the moment we need it.”
• “The most significant challenges and changes have been the budgets have been slashed for projects/training/user communication in general. No time/budget/interest in keeping me trained in my field. That is my biggest challenge right now. Years ago, I was regularly sent by FPC to conferences/seminars. Now it’s a rare event.”

Can you imagine how these same writers must feel now? How do you keep up? In a recent post, I polled writers to find out how much time they felt they should devote to learning technology each day to be successful in their role. Of the 40 responses, about 30% said 30 minutes, 30% said 1 hour, and 15% said 2 hrs.

But I also asked how much time they actually devote to learning technology each day. 27% said 0 minutes, 30% said 20 minutes, 19% said 30 minutes, and only 13% said 1 hour (see Strategies for learning technology – podcast recommendation and a poll).

Given how much technical knowledge you need to be functionally able to write documentation in today’s landscape, how can one possibly ramp up the right level of knowledge by just spending 30 minutes or less each day? I felt I would need 2 hours a day to feel comfortable writing in some of these domains, but as another writer noted, it’s not always clear where to start. There is such diversity in what we document, it can be like moving from one long line to another long line in an amusement park — spending hours of learning just to be able to write one sentence that lasts 30 seconds.

In the end, who has 2 hours a day to carve out time for this learning, either at work or home? It’s nearly impossible unless you incorporate it into your job itself.

Technical knowledge is essential to writing

Despite the difficulty in learning and keeping up with technology, technical knowledge is essential if you want to write documentation for engineers or other specialists. Without a comfortable understanding of the technical knowledge, your ability to write becomes crippled.

Because of this need for strong technical knowledge, James Neiman, an experienced API technical writer, says that tech writers need engineering backgrounds, such as a computer science degree or previous experience as an engineer to excel in API documentation roles. Neiman says tech writers often need to look over a developer’s shoulder, watching the developer code or listening to an engineer’s brief 15-minute explanation, and then return to their desks to create the documentation. He says you might need to take the code examples in Java and produce equivalent samples in another language, such as C++, all on your own.

Take a look at this video of Neiman and Andrew Davis (a recruiter for API tech writers in the Bay area) presenting on Finding the right API Technical Writer at an API conference in London. Their presentation format includes a Q&A exchange between the two. Scrub to around the 22-minute mark for the relevant part:

Here’s a transcript of the exchange:

Andrew: Can a tech writer without a development background write great API documentation?

James: Absolutely not. There is no way that a busy engineering team has time to train a person without a computer science degree. That’s just the reality of it. Engineers at best can speak to you in some version of English, which may or may not be their native language. They don’t have a lot of time, and they expect you to finish their thoughts for them. That means that you need to be able to sit next to them and look at how they’re coding, and then be able to replicate that and extend it and even create examples.

They may say, “Here’s an example. You can extend it, add on these other APIs, work out this use case for us. We haven’t had time to finish this.” They can say, “Well, let me show you how this works in Objective C; we also support this on Java. Can you create something similar on Java?”

If you don’t have that kind of development background, it’s unrealistic that you could expect to train, for example, somebody with a master’s degree in English (and who is a very intelligent person but otherwise not technical) to do such a thing.

The focus here is on API documentation for developers, but I think a similar case could be made for other specialized engineering domains, from airplane maintenance procedures to pharmaceutical testing algorithms.

One approach to ramping up on this complexity might be to reduce your scope a bit and focus in on 1-2 projects in more immersive, in-depth ways than you could with 5-6 projects. However, as I noted earlier, it appears that the ratio of technical writers to developers is getting wider.

Another approach might be to spend more time in online courses and textbooks at work. This would reduce your productivity in the short-term, but it might increase your productivity in the long-term. But even if I were to start a steady course of C# learning, I doubt I’d be able to convert Java code samples to C# without engineering involvement.

Some push back on Neiman’s standards for technical knowledge. James Rhea says says that “adequate” technical knowledge is usually enough to get the job done, and acquiring deeper technical knowledge has somewhat diminishing returns, since it means other aspects of documentation will likely be neglected. Rhea explains:

I wouldn’t aim for deep technical knowledge. I would aim for adequate technical knowledge, recognizing that what constitutes adequacy may vary by project, and that technical knowledge ought to grow over time due to immersion in the documentation and exposure to the technology and the industry.

I speculate that the need for writers to have deep technical knowledge diminishes as Tech Comm teams grow in size and as other skills become more important than they are for smaller Tech Comm teams. I’m not claiming that deep technical knowledge is useless. I’m suggesting that (to frame it negatively) neglecting deep technical knowledge has less severe consequences than neglecting content curation, doc tool set, or workflow considerations. (Adding Value as a Technical Writer)

In other words, if you spend excessive amounts of time learning to code, at the expense of tending to other documentation tasks such as shaping information architecture, analyzing user metrics, tending to localization workflows, developing user personas, ensuring clear navigation, and more, your doc’s technical content might improve a bit, but the overall doc site will go downhill (just look at any internal company wiki as an example). Also, at some point, your knowledge will start to overlap the engineer’s knowledge, so you’ll end up with redundant capabilities.

At any rate, there is surely a good balance to be achieved between “technical” and “writing.” While you don’t need a specialist’s understanding of a subject matter, some familiarity is necessary, if only to understand the right terms and foundational concepts.

Embracing a more collaborative role in authoring specialized content

In some companies, when we escalated concerns about needing more resources so that we could immerse and engage more fully with teams, executives responded by explaining that the company couldn’t afford to hire armies of tech writers, but that we had to “lean-in” on product teams to produce the documentation themselves. In other words, we would act more like editors and publishers, while the engineers did more of the content development.

There are all kinds of problems with having engineers write. I don’t want to go into the problems too much here. (First is that engineers often don’t want to write, or if they do, they put such little effort into writing that it becomes a nightmare to fix. And since many engineers aren’t native English speakers in the first place, the content they write combined with the technology terms and lingo can become a nearly impenetrable jungle for the technical writer/editor to navigate. In some happy scenarios, engineers turn out to write quite well, though.)

However much I dislike the model where engineers develop content and technical writers add information usability, this just might be the norm in years to come. If the content is so specialized that only engineers can fully articulate it at the required level, then technical writers will play more supporting editorial roles, guiding engineers with content creation and making the information more readable/usable.

The degree to which engineers collaborate in the documentation process falls along a spectrum, for sure. But I don’t see how we can accommodate increasing amounts of specialization and complexity in the technology landscape without also incorporating more engineers into the writing process.

I’ve found that engineers are actually good at writing certain kinds of docs, and poor at others. Engineers excel at writing reference documentation, especially when there are standards they’re writing to (such as the OpenAPI specification). Engineers are also good at commenting on code samples, which is an area where technical writers often fall short. Engineers aren’t nearly as good with conceptual documentation and tutorials, in part because they’re too close to the material.

Note that playing more of an editorial/publisher role does not remove the technical writer’s need for adequate technical knowledge. Unless you have some familiarity with the technology domain, you’d be limited only to stylistic edits. One must have a basic understanding of the technology domain to shape coherence, clarity, terminology, goals and information needs, etc.

However, recognizing that documentation is now a collaborative effort more than before helps me set certain expectations and workflows. It removes some of the pressure of feeling like I need to constantly acquire in-depth specialized knowledge to do my job. Playing an editorial role also helps me focus on the information usability aspects of content. When you’re elbow-deep writing content, you might run out of time/energy to address some of these other often overlooked aspects of information usability. Some of these information usability elements might include the following:

• Workflow and process maps across the content
• Visual diagrams and other multimedia to assist with key concepts
• Glossaries and alignment with industry standard terminology
• Information harmony for the topic across the entire dev portal
• Distillation of information into high-level summaries and quick reference guides
• Conducting surveys and feedback about the user experience
• Alignment of the product story with the user story

(It’s kind of like cooking — when someone spends hours cooking dinner, they don’t have the energy to also clear the table and wash the dishes. Cookers aren’t cleaners, as they say.)

Finally, it’s worth noting that because more engineers are contributing to documentation, there has also been a significant shift in authoring and publishing tools and processes. Much of the tech comm industry (particularly in developer documentation domains) has shifted from XML to Markdown and docs-as-code tools because most developers find XML too cumbersome and tedious, and Markdown so easy.

For example, Microsoft’s developer docs were previously in XML, but they have since switched to a docs-as-code model. Check out Open Authoring – Collaboration Across Disciplines, by Ralph Squillace, for details. Microsoft is one of many companies making this switch. Google made huge strides in their internal documentation when they adopted an engineering approach of including Markdown files directly in repositories (see Documentation, Disrupted: How two technical writers changed Google engineering culture for more details). I also recently learned that Citrix’s developer docs just switched from an XML model to a docs-as-code model.

Conclusion

So, summing it up. What trends are we seeing? One underlying trend is that technology seems to be getting more specialized and complex. This trend toward specialization is driving up the value of technical knowledge, making it more prized than writing skills. To handle the complexity, technical writers may find that they are playing increasingly collaborative roles with engineers to create the needed documentation. To drive up their value in organizations, technical writers should look for ways to collaborate more skillfully with engineers in creating content.

Your reactions and input

Answering these questions helps me understand how much you agree or disagree with the assertions I made in this post.

You can see the results (so far) here.

Slides

For slides related to this topic, see https://idratherbewriting.com/trends-collaboration-with-engineers/.

References

2016-2017 STC Salary Database (based on 2016 data). Society for Technical Communication. Retrieved Oct 2018.

Aguinaga, Jose. “How it feels to learn JavaScript in 2016.” Hackernoon. 3 Oct 2016.

Arbesman, Samuel. Overcomplicated: Technology at the Limits of Comprehension. Penguin, New York. 2016.

Brumberger, Eva and Lauer, Claire. “The Evolution of Technical Communication: An Analysis of Industry Job Postings.” Technical Communication, Volume 62, Number 4. Nov 2015.

Davis, Andrew. “Finding the right API Tech Writer?” SynergisTech. 20 Oct 2016.

Grey, Jim. “Software technical writing is a dying career (but here’s what writers can do to stay in the software game).” Delivering software through leading people well. 16 June 2015.

Highsmith, Jim; Mason, Mike; Ford, Neal. “Implications of Tech Stack Complexity for Executives.” Thoughtworks. 16 Dec 2015.

Johnson, Robert R. “Craft Knowledge: Of Disciplinarity in Writing Studies.” College Composition and Communication, Vol. 61, No. 4. June 2010.

Johnson, Tom. “If writing is no longer a marketable skill, what is?” Idratherbewriting. 9 Aug 2018.

Johnson, Tom. “Number One Issue for Technical Writers Today: Keeping Pace with Rapidly Evolving Technology.” Idratherbewriting.com. 1 Mar 2007.

Johnson, Tom. “Strategies for learning technology – podcast recommendation and a poll.” Idratherbewriting.com 10 Aug 2018.

Lanier, Clinton. “Analysis of the Skills Called for by Technical Communication Employers in Recruitment Postings.” Technical Communication, Volume 56, Number 1. Feb 2009.

Malone, Thomas; Laubacher, Robert; Johns, Tammy. “The Big Idea: The Age of Hyperspecialization.” Harvard Business Review July-August 2011 issue.

Pratt, Ellis. “40. The evolution of the technical communicator’s career.” Cherryleaf. 2 Aug 2018.

Rhea, James. “Adding Value as a Technical Writer.” Within the Ordinary. 21 Dec 2016.

“Software Developers.” Bureau of Labor Statistics: Occupational Outlook Handbook. 13 Apr 2018.

“Technical Writers.” Bureau of Labor Statistics: Occupational Outlook Handbook. 13 Apr 2018.

Thangavelu, Poonkulali. “Companies That Went Bankrupt From Innovation Lag.” Investopedia. Retrieved Oct 2018.