I'd Rather Be Writing-logo

I'd Rather Be Writing

Technology News >

Technical writing podcast. Includes tech comm (technical communication) presentations at venues such as Write the Docs and STC, audio versions of posts from I'd Rather Be Writing (idratherbewriting.com), and more. This tech writing podcast's focus is on documentation, user guides, user assistance, tutorials, and other topics for technical writers, technical communicators, content strategists, and documentarians. Produced by Tom Johnson.

Technical writing podcast. Includes tech comm (technical communication) presentations at venues such as Write the Docs and STC, audio versions of posts from I'd Rather Be Writing (idratherbewriting.com), and more. This tech writing podcast's focus is on documentation, user guides, user assistance, tutorials, and other topics for technical writers, technical communicators, content strategists, and documentarians. Produced by Tom Johnson.
More Information

Location:

United States

Description:

Technical writing podcast. Includes tech comm (technical communication) presentations at venues such as Write the Docs and STC, audio versions of posts from I'd Rather Be Writing (idratherbewriting.com), and more. This tech writing podcast's focus is on documentation, user guides, user assistance, tutorials, and other topics for technical writers, technical communicators, content strategists, and documentarians. Produced by Tom Johnson.

Twitter:

@tomjohnson

Language:

English

Contact:

408-781-2129


Episodes

How to avoid being a secretary for engineers

11/19/2018
More
If we just see our task as documenting solutions that engineers have solved, it removes the creativity and critical thinking dimension from tech comm. The creative dimension in tech comm comes into play as we identify and solve tech comm challenges, such as devising ways to simplify complexity or otherwise improve the user experience.

Duration:00:19:10

I'd Rather Be Writing is now an Alexa Flash Briefing skill

11/5/2018
More
Now you can listen to the latest narrated post on I'd Rather Be Writing as an Alexa Flash Briefing skill. This means you can listen to my audio content through your Echo device.

Duration:00:10:04

Upcoming full-day API documentation workshop in Menlo Park

10/31/2018
More
I'm giving a full-day API documentation workshop on Nov 8, 2018, in Menlo Park, California, in coordination with Scott Abel (aka, The Content Wrangler). There are still a few open spots left in the workshop.

Duration:00:00:48

Preferring technical acuity over specialized knowledge

10/24/2018
More
In the debate between being a specialist or generalist, there's also a third option: developing technical acuity. A person with a high degree of technical acuity has the technical mindset needed to understand and solve problems across a variety of technical domains. Given the ever growing number of technologies, developing technical acuity can be more advantageous, especially in technical writing contexts since technical writers work with a lot of different technologies.

Duration:00:09:38

If writing is no longer a marketable skill, what is?

8/9/2018
More
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.

Duration:00:30:16

My conflicted thoughts about the decentralized web (while taking the Census of Technical Communicators survey)

8/6/2018
More
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...

Duration:00:32:26

Articulating stories that influence product adoption (new article in Simplifying Complexity series)

7/31/2018
More
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...

Duration:00:36:52

Reducing the complexity of technical language (new article in Simplifying Complexity series)

7/11/2018
More
I added a new article in my ongoing series about simplifying complexity. The article is called Reducing the complexity of technical language and explores reasons why the language in technical documentation tends become so full of jargon and other unfamiliar terms, and a few solutions for simplifying the language. I emphasize the need to read the competitor's documentation and other articles in the industry to get a sense of the right terms and contexts that users likely expect. I also...

Duration:00:49:02

The relationship between academics and practitioners — Podcast with Kirk St. Amant

7/11/2018
More
In this podcast, I chat with Professor Kirk St. Amant about the relationship between practitioners and academics. Kirk recently co-authored an article about research as a unifying focus to bring academics and practitioners together. Using this article as the basis for discussion, we dive into origins of the divide, why both practitioners and academics of the same field need each other, potential solutions, and more.

Duration:00:41:41

Evaluating the user experience of documentation -- Podcast with Bob Watson

6/18/2018
More
This week I chatted with Bob Watson, an assistant professor of tech comm at Mercer University, about how to evaluate the user experience of documentation. The idea of doing a podcast came up during a comment thread on a previous post about reconstructing the absent user. We had a long exchange in the comment threads and thought it would be good to have a podcast about the topic.

Duration:00:58:25

Recording of API documentation workshop in Denver

3/12/2018
More
I recently gave a half-day API workshop in Denver on March 10, 2018. Topics in the workshop included how to document reference API content (endpoints, parameters, requests, etc.), what non-reference topics (for example, status and error codes, rate limiting, getting started, sample apps) are common, how to create an OpenAPI specification document and Swagger UI output, and more. You can view a recording of the workshop, browse the slides, and listen to the audio here. Because of the...

Duration:08:51:16

Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation

3/8/2018
More
I recently gave a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018. You can browse the slides and listen to the audio recording here.

Duration:01:06:14

Recording of OpenAPI and Swagger presentation (for STC and WTD San Diego)

2/14/2018
More
I recently gave a presentation to the STC San Diego chapter and WTD San Diego group called "Swagger UI and the OpenAPI specification" (February 13, 2018). You can view a recording of the presentation, browse the slides, and listen to the audio here.

Duration:01:13:59

Recording of WTD South Bay presentation: Publishing tools for API documentation

1/19/2018
More
I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. You can view a recording of the presentation, browse the slides, and listen to the audio here.

Duration:01:07:00

How to become a voracious reader

12/1/2017
More
Voracious reading begins with voracious thinking. Asking questions gives us a purpose and drive for reading.

Duration:00:07:28

How do you communicate user progress in a course without a Learning Management System (LMS)?

11/28/2017
More
When you don't have a system that logs users in and tracks their progress, it can be a challenge to show their progress in a course. However, rather than showing progress through completed pages, quizzes, or other interactive exercises, progress can also be measured through larger user goals that extend beyond the course. In the case of my API documentation course, the user's goal is to break into the field of API documentation, not so much to finish a course. Breaking into API documentation...

Duration:00:09:39

Intro to API Documentation -- recording of presentation to STC Silicon Valley chapter on 11/20/2017

11/19/2017
More
I recently gave a presentation titled "Introduction to API Documentation" to the STC Silicon Valley chapter in Santa Clara, California. The video recording and audio are available here.

Duration:00:51:39

SwaggerHub: A collaborative platform for working on OpenAPI/Swagger specification files, and more

10/5/2017
More
When documenting REST APIs, the OpenAPI specification (formerly called Swagger) is pretty much the default standard. Yet learning the OpenAPI spec is not a trivial undertaking and requires significant ramp-up. SwaggerHub is a tool can reduce the complexity in creating your OpenAPI spec file because it enables collaboration between both developers and technical writers. This collaboration not only helps compensate for gaps in understanding with the spec, SwaggerHub also offers many other...

Duration:00:11:27

Has plain language deepened or ruined our delight in language?

9/20/2017
More
Although technical writers champion plain language, embracing plain language for many years can cripple your ability to use more eloquent language, like that of a literary author or essayist. There isn't much room for literary play or playful tones in technical documentation. Following the rules of simple language has distorted my ability to read anything that blatantly violates those rules without questioning the author's word choice and sentence construction. Sometimes I feel that simple...

Duration:00:19:55

Discoveries and realizations while walking down the Docs-as-Code path

8/23/2017
More
This past week I had some good discussions with developers about the right directions in our doc-as-code project at work. I say good discussions, but actually they were challenging. The outcome led me to realize more details about embracing docs as code. The more you treat docs as code, the more you may have to set aside some common tech writer models of handling content and instead embrace the software code workflows entirely. Some of these principles include storing only source code in...

Duration:00:27:31