Tech comm trends: Providing value as a generalist in a sea of specialists (Part I)
Technical writing jobs have shifted more from the end-user domain to the developer domain. This creates challenges because most technical writers are generalists, not specialists, when it comes to technology they document. In these specialist contexts, technical writers can add value by focusing on authoring/publishing processes and tools, knowledge of the user experience, and information usability.
Tech comm trends: Providing value as a generalist in a sea of specialists (Part II)
Thanks to UX design, technology is becoming a simpler experience for end-users; however, the code is becoming more complex behind the scenes. As a result, more technical writing jobs are transitioning to the areas of complexity in the developer domain. Because content in the developer domain is so technical and specialized, many developers are collaborating and assisting with the documentation. As developers get involved in docs, they usually adopt docs-as-code tools, writing in simpler Markdown files.
Tech comm trends: Providing value as a generalist in a sea of specialists (Part III)
When specialists write docs, they tend to stick with simple formats and tools. As a result, incorporating structure or writing to specifications often gets overlooked. This is one area where technical writers can add value.
Tech comm trends: Providing value as a generalist in a sea of specialists (Part IV)
Specialists often lack user feedback to guide and inform their decisions. This is an area that technical writers can provide value, especially in helping identify problem areas in the user experience.
Tech comm trends: Providing value as a generalist in a sea of specialists (Part V)
When specialists write, they often neglect principles of information usability that can make their content more easily consumable by readers. Some of these principles include letting users switch between macro and micro views, making information discoverable as the user needs it, ensuring information harmony in the larger landscape, and reducing and distilling vast information down to its essence.
Tech comm trends: Providing value as a generalist in a sea of specialists (Part VI)
My discussion of information usability principles continues here. Some additional information usability principles include conforming to the patterns and expectations of the genre and schemas, reducing the complexity of technical language, and iterating and incrementing on content following an agile approach.
Tech comm trends: Providing value as a generalist in a sea of specialists (Part VII)
Wrapping up this series, the conclusion recaps the argument highlights and information usability principles.
Tech comm podcasts roundup and survey
The latest Cherryleaf podcast lists the available tech comm podcasts and how to get started with your own podcast. I created a short survey about podcasts to gather some feedback about your listening habits and preferences.
Pages at a glance -- the importance of the first two sentences of any topic
Showing users the 'Pages at a glance' when they click a folder title in a sidebar can help users get a quick understanding of the whole without slogging through the details of each page. The first two sentences of a topic should encapsulate the point of the whole topic is a condensed and informative way.
Write the Docs Podcast Episode 16: An open-source Grammarly for tech docs?
This episode focuses mainly on testing tools. Last month, some rockstar WTD community members spent a few days at the Pronovix offices in Szeged, Hungary, trying to create a series of open-source testing tools. Specifically, they wanted to create a ‘create a container deployable solution that can automatically check docs’. In more blunt terms, a kind of open-source Grammarly, but integrated into deploys and repositories and focused on tech docs.
How I handled data for about 10 device specifications on the same page -- the advantages of a flexible, customizable web-based framework like Jekyll
Jekyll provides flexibility and customization in ways that make it extremely attractive for addressing complex scenarios. You can separate data from the presentation layer, define templates, and iterate through data to populate the templates. In this post, I explain how I approached a device specifications page that has specs for about 10 different devices all shown on the same page.
New article in Simplifying Complexity series -- Iterate and increment on content following an agile approach
I added a new article in my Simplifying Complexity series about iterative content development. The article is titled 'Iterate and increment on content following an agile approach'. This is a principle I feel strongly about as a central approach in all writing, but one with particular application to complex scenarios.
Getting a job in API documentation -- new topics and expansions in my API doc course
I recently expanded the Getting a job in API documentation section in my API documentation course. This section explores issues such as why API technical writers need programming knowledge, the tradeoffs between being a writer who learns programming versus a programmer who learns writing, states in the U.S. where most of the API documentation jobs are located (and whether you should move there), and more.
Strategies for learning technology -- podcast recommendation and a poll
Learning technology is a core task for thriving in developer docs. Here's a great podcast recommendation and a poll on this topic.
If writing is no longer a marketable skill, what is?