Search results

Tech comm trends: Providing value as a generalist in a sea of specialists (Part VII)

Series: Tech comm trends: Providing value as a generalist in a sea of specialists

by Tom Johnson on Oct 2, 2018
categories: api-doc simplifying-complexitywriting

Wrapping up this series, the conclusion recaps the argument highlights and information usability principles.

Summing it up

I covered a lot of ground in this essay. I argued the following:

  • Technology is becoming increasingly specialized, particularly with developer documentation.
  • Since tech writers are generalists, the task of documenting specialized technology often becomes daunting.
  • Because the information is so specialized, many developers participate and collaborate in the authoring process.
  • To provide value in specialist contexts, tech writers can focus on (1) authoring/publishing processes and tools, (2) knowledge of the user experience, and (3) information usability.

Within the topic of information usability, I covered 7 principles:

  • Principle 1: Let users switch between macro and micro views
  • Principle 2: Make information discoverable as the user needs it
  • Principle 3: Ensure information harmony in the larger landscape
  • Principle 4: Reduce and distill vast information down to its essence
  • Principle 5: Conform to the patterns and expectations of the genre and schemas
  • Principle 6: Reduce the complexity of technical language
  • Principle 7: Iterate and increment on content following an agile approach

I list some additional information usability principles on my site,, and I’ll continue to add to them in the future.

I also included a number of surveys throughout this essay to gather your feedback and input about whether you agree/disagree, and to what extent. I highly value the insights from readers and think that the perspectives shared as a whole can often provide guidance in lack of more rigorous studies or data.

Overall, by focusing on these three areas, we can hopefully move past some of the second-class feelings that we sometimes get when surrounded by specialists who seem to possess deep knowledge and value to organizations. If you do all of these things, you’ll contribute in significant, valuable ways to your organization. But will your company recognize it and value your role and contributions? Proving that value is not easy, but at least with the right focus, you can be confident that you’re moving in a productive direction.

Your reactions and input?

You can see the responses (so far) here.


Albers, Michael. “Complex Problem Solving and Content Analysis.” Content and Complexity: information Design in Technical Communication. Edited by Albers, Michael and Mazur, Beth. Routledge. 2008.

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

Content and Complexity: information Design in Technical Communication. Edited by Albers, Michael and Mazur, Beth. Routledge. 2008.

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

Atwood, Jeff. “This Is What Happens When You Let Developers Create UI.” Coding Horror. 27 Nov 2006.

Baker, Mark. Structured Writing: Rhetoric and Process. XML Press, Sept 2018.

Courtney, Jonathan. “The Golden Age of UX Is Over.” UX Planet. 26 Jul 2017.

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.

Johnson, Tom. “Transparency in documentation: dealing with limits about what you can and cannot say.” 13 Jul 2017.

Johnson, Tom. “Recording of Open Authoring – Collaboration Across Disciplines presentation, by Ralph Squillace.. 15 Nov 2016.

Lichaw, Donna. The User’s Journey: Storymapping Products That People Love. Rosenfeld. March 2016.

Lane, Kin. “Using Plain Language In Your API Paths.” API Evangelist. 9 Jul 2018. .

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

Moell, Patricia et al. “The Evolving Role of the Technical Editor.” STC Intercom, Sep 2012.

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

Robillard, Martin and Uddin, Gias. “How API Documentation Fails”. IEEE Software. Volume: 32, Issue: 4, July-Aug. 2015.

Scott Ambler + Associates. “Core Practices for Agile/Lean Documentation”. Agile Modeling.

Society for Technical Communication. 2016-2017 STC Salary Database.

Spence, Ian and Bittner, Kurt. What is iterative development? — Part 1: The developer perspective. IBM Developer Works. 15 March 2005.

St. Amant, Kirk. “Reflexes, Reactions, and Usability: Examining How Prototypes of Place Can Enhance UXD Practices.” Communication Design Quarterly 6.1 2018.

Watson, Bob. “If your API is hard to document, be warned.” Docs by Design. 18 Feb 2018.

van der Meij, Hans; Blijleven Peter; Jansen, Leanne. “What Makes Up a Procedure?”. Content and Complexity: information Design in Technical Communication. Edited by Albers, Michael and Mazur, Beth. Routledge. 2008.

van der Meij, Hans. “Horace Hockley Award Winner 2015.” Institute of Scientific and Technical Communicators. Spring 2016.

About Tom Johnson

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.