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.
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.
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.
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.
Learning technology is a core task for thriving in developer docs. Here's a great podcast recommendation and a poll on this topic.
When we try to sell our tech comm skills, promoting our writing skills doesn't seem to impress people anymore, as writing is considered more of a presumed skill everyone has. To give a sense of value, we need to hyphenate our job titles, becoming more of a hybrid professional.
Seeing my name in the Census of Technical Communicators survey as a possible source for professional development made me think about the impact of blogs as a learning resource. Advertising encourages bloggers to create rapid-fire, lightweight content in order to increase page views and other attention on the advertised product or service. The proliferation of blog content turns the wheels of social media, creating micro-bursts of attention for companies. The negative impact, however, is that more traditional forms of learning, such as scholarly journal articles and books, take a hit. The web's architecture and monetization model around content is optimized for blog content, so unless other mediums can find a way to become more visible and engaging within the architecture of the web, they will continue their slide into invisibility (at least to mainstream users).
When contributing to a corporate blog, the stories that get the most traction and approval are how-to stories about overcoming technology challenges. These stories are much the same ones that we tell in documentation.
I added a new article in my ongoing series about simplifying complexity. The article is called Articulating the invisible stories that influence product adoption or rejection and explores why adoption of our products among users doesn't often live up to our expectations. I argue that we need to articulate the story we're telling about the product as well as the story users tell, and identify whether the two are in alignment. Note that you can both read and listen to this article, since I created an audio recording for it.
In this conversation post, I chat with Guiseppe Getto about the reciprocal influences within networks that contribute towards better knowledge creation. We talk about the iFixit's Technical Writing project, Latour's Actor-Network Theory, the revolution of the spudger in circumventing corporate non-repair agendas, why students learned to triple-check their work and begin tinkering deeply with broken devices, and more.
In this conversation post, I chat with Lisa Melonçon about the theoretical underpinnings of tech comm, mainly its connection to rhetoric that allows tech comm to get a seat at the English table within academia. We chat about what rhetoric is, why it is or isn't important to tech comm today, and why constant participation and involvement is critical for inclusion within either academia or the workplace.
In this conversation with Carlos Evia, we focus mostly on lightweight DITA, exploring what led to his initial interest in DITA, what it means to focus on technology in the context of academia, why more general academic research hasn't focused on DITA (but has investigated single-sourcing and content re-use), why DITA can be so polarizing, his participation in OASIS on the DITA committee and how the standards process works, and more.
After a short summer break, we've returned to the WTD podcast and taken up our mics again to talk about important doc issues. In this episode, we first chat about assumptions we have regarding our users and the value of doing user research. Basing the discussion on Jen Lambourne's talk at WTD Portland 2018, we talk about ways to capture the user perspective and limitations/workarounds for user research within the corporate domain. Next, we chat about an article by Emily January Petersen on the Make-It-Pretty Philosophy, where the roles of tech writers are reduced to grammar and style editing only, without more substantive updates and revisions to content. Finally, we talk about Tom's research project on healing the academic/practitioner divide and how he hopes his conversation posts will bring both sides more closely together.
The following is a guest post by Melonie McMichael, a senior instructor at the University of Colorado and the proprietor of Technodaptability. In this post, she explores the challenge of teaching technology to students in tech comm programs, arguing that perhaps the chief challenge of teaching adaptability is the need to be adaptable ourselves.
In this guest post, Emily January Petersen, an assistant professor at Weber State University in the Professional and Technical Writing Program, talks about stereotypes in the workplace that devalues the work of technical and professional communicators. These myths perpetuate the idea that technical communication work is cosmetic, secretarial, unknown, and unnecessary.
