Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

Stitcher radio

Search results

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

Part VII: Conclusion

by Tom Johnson on Oct 2, 2018 • 0 Comments
categories: api-docsimplifying-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.

follow us in feedly