I'd Rather Be Writing

I'd Rather Be Writing

idratherbewriting.com
Technical writing trends, innovations, and news. Content original from idratherbewriting.com. Hosted by Tom Johnson.


Are technical writers increasingly playing non-technical roles? Some thoughts on the evolution of technical writing roles
Mar 30 • 26 min
How is the role of the technical writer evolving? It seems we’re moving away from writing and more towards other roles, such as reviewer/convener, user champion, editor, publisher, and promoter. However, it’s difficult to gauge change, especially across…
Podcast: Users as producers of knowledge — conversation with Nupoor Ranade about how tech writer roles are changing
Mar 29 • 50 min
How can users shape and influence the documentation you’re producing? In this podcast, I chat with Nupoor Ranade, PhD candidate at North Carolina State University, about how the roles of technical writers are changing. Instead of writers authoring content…
Webinar recording: How Trends in API Documentation Differ from other Tech Comm Trends
Mar 12 • 59 min
I recently gave a webinar on trends in developer docs to the STC Washington DC chapter on March 12, 2020. In this presentation, I presented the results and analysis of my Trends in Developer Documentation 2020 survey. A recording and audio file is…
Introduction to API documentation - Recording from Los Angeles API documentation workshop
Mar 11 • 88 min
In January I gave an API documentation workshop in Los Angeles, and I recorded the first section of the workshop. This section provides an introduction to APIs, including an overview of APIs, the API doc market, info about API popularity, how to submit…
Podcast: How Paligo is filling a niche in the CCMS market for complex documentation, with Anders Svensson
Mar 9 • 51 min
I recently chatted with Anders Svensson about how Paligo, a cloud-based CCMS, is filling a niche in the CCMS market for complex documentation needs. Complex documentation refers to documentation with multiple product variants, versions, languages,…
Podcast with Andrew Davis: Hiring API doc writers — an inside look at fixing broken processes
Feb 23 • 55 min
I recently chatted with Andrew Davis, a recruiter for API documentation positions in the San Francisco Bay area, about why it’s so difficult to hire technical writers for developer documentation roles. Andrew has more experience and knowledge with…
From API docs to developer portals
Feb 9 • 32 min
One comment I often hear from API workshop participants and other readers is that they want a more advanced API course. I’ve been thinking about what that more advanced course would involve, in addition to what might be involved in leveling up at my work,…
Podcast: API Design and Usability with Arnaud Lauret (API Handyman)
Dec 7, 2019 • 54 min
Arnaud Lauret, also known as the API Handyman, recently published a book called The Design of Web APIs. In this podcast, I chat with Arnaud about his book, specifically exploring best practices for designing web APIs and focusing on the roles technical…
Podcast: Dealing with Project Overload — Strategies to Manage Overflowing Documentation Tasks
Oct 2, 2019 • 20 min
In this podcast, I talk about how to deal with project overload, specifically covering strategies to manage tasks. Scrum is one framework for dealing with project work by allowing you to limit the work you have before you in a more systematic way. I also…
Podcast: 10 myths about API documentation
Sep 29, 2019 • 31 min
In this podcast, I debunk 10 myths about API documentation. For example, some myths are that only engineers can write API docs, or that you have to write API docs by deciphering an engineer’s source code. In this podcast, I go through these myths one by…
Recording of Tech Comm Trends Presentation (STC Puget Sound chapter)
Jun 8, 2019 • 86 min
I recently gave a presentation on technical communication trends to the STC Puget Sound Chapter in Seattle, Washington, on May 21, 2019. This is one of the better presentations on trends I’ve given and culminates a lot of research and other iterations on…
Crash course in API documentation — a one-hour video
May 16, 2019 • 58 min
If you want a condensed, one-hour version of what I cover in my API documentation workshop, check out this crash-course video.
Corporate exodus narratives: A close look at the tension between the corporation and academia
Mar 1, 2019 • 27 min
Corporations often expect tech comm academics to fashion their curriculums to suit corporate needs; in contrast, academic departments want to give students a safe space free of corporate agendas for critical inquiry. Tech comm academics are often caught…
Recording and slides for my trends presentation at the Symposium for Communicating Complex Information (SCCI)
Feb 24, 2019 • 42 min
This week I traveled to Louisiana to attend the Symposium for Communicating Complex Information and presented on tech comm trends. You can listen to the recording, view my slides, and read my latest thoughts on trends here.
How to become a 10X technical writer in the workplace
Feb 7, 2019 • 23 min
How do you become a 10X technical writer in the workplace (10X means 10 times more efficient and productive than others)? In this post, I raise the question and then offer a few tips I try to follow: (1) Record your meetings with engineers, (2) Respond…
How to motivate users to provide feedback: Show that you’re listening to their input
Feb 1, 2019 • 9 min
To encourage users to leave more feedback, add a contact email field on your feedback submission form. When you receive feedback, provide a quick response that shows you’re listening and taking action on their input.
Site analytics from Jan 1 to Dec 31, 2018 — are more engineers writing docs now?
Jan 14, 2019 • 33 min
Every year, when I re-examine my site analytics, I take the time to reflect on trends I’m seeing with traffic to my own site. Not necessarily industry trends, just trends about which topics are popular on my site. Based on these trends, I assess and…
Recording for Menlo Park API documentation workshop now available — and some thoughts on using cardioid versus omnidirectional microphones for recording
Dec 4, 2018 • 11 min
The recording for the full-day API workshop that I recently gave in Menlo Park, California, is now available. This recording provides more than 5 hours of instruction about writing API docs — for free. I also share some thoughts on cardioid versus…
New post in Simplifying Complexity series — Principle 11: Be both a generalist and specialist through your technical acuity
Nov 30, 2018 • 62 min
In my Simplifying Complexity series, I added a new post called, Principle 11: Be both a generalist and specialist through your technical acuity. I also recorded this essay as a narrated podcast.
How to avoid being a secretary for engineers
Nov 19, 2018 • 27 min
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…
I’d Rather Be Writing is now an Alexa Flash Briefing skill
Nov 5, 2018 • 8 min
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.
Upcoming full-day API documentation workshop in Menlo Park
Oct 31, 2018 • 1 min
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.
Preferring technical acuity over specialized knowledge
Oct 24, 2018 • 13 min
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…
If writing is no longer a marketable skill, what is?
Aug 9, 2018 • 25 min
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…
My conflicted thoughts about the decentralized web (while taking the Census of Technical Communicators survey)
Aug 6, 2018 • 24 min
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…
Articulating stories that influence product adoption (new article in Simplifying Complexity series)
Jul 31, 2018 • 43 min
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…
The relationship between academics and practitioners — Podcast with Kirk St. Amant
Jul 11, 2018 • 56 min
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…
Reducing the complexity of technical language (new article in Simplifying Complexity series)
Jul 11, 2018 • 43 min
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…
Evaluating the user experience of documentation — Podcast with Bob Watson
Jun 18, 2018 • 58 min
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…
Recording of API documentation workshop in Denver
Mar 12, 2018 • 231 min
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…
Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation
Mar 8, 2018 • 59 min
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.
Recording of OpenAPI and Swagger presentation (for STC and WTD San Diego)
Feb 14, 2018 • 61 min
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.
Recording of WTD South Bay presentation: Publishing tools for API documentation
Jan 19, 2018 • 65 min
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.
How to become a voracious reader
Dec 1, 2017 • 6 min
Voracious reading begins with voracious thinking. Asking questions gives us a purpose and drive for reading.
How do you communicate user progress in a course without a Learning Management System (LMS)?
Nov 28, 2017 • 14 min
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…
Intro to API Documentation — recording of presentation to STC Silicon Valley chapter on 11/20/2017
Nov 19, 2017 • 65 min
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.
SwaggerHub: A collaborative platform for working on OpenAPI/Swagger specification files, and more
Oct 5, 2017 • 16 min
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…
Has plain language deepened or ruined our delight in language?
Sep 20, 2017 • 18 min
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…
Discoveries and realizations while walking down the Docs-as-Code path
Aug 23, 2017 • 23 min
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.…
Why Stack Overflow’s Documentation effort failed — a few thoughts from a technical writer’s perspective
Aug 5, 2017 • 12 min
Stack Overflow, mostly known as a forum for answering niche software questions, recently tried to launch a Documentation component to their site. The goal of Documentation was to ‘do for Documentation what we did for Q&A’. In other words, provide…
Tech docs and Agile: Alternatives to integrating into engineering Scrums (Part 2)
Aug 4, 2017 • 31 min
This is part two in a series on Agile and tech docs. In the previous post, I outlined challenges in integrating into engineering Scrum teams. Some alternatives to Scrum include Kanban, Extreme programming, Waterfall, and various productivity…
Tech docs and Agile: Problems with integrating tech writers into engineering Scrums (Part 1)
Aug 4, 2017 • 35 min
Although it seems like documentation should be treated like other features worked on by a Scrum team, frequently it is not. When tech writers try to integrate into engineering Scrum teams, they usually run into a host of challenges. These challenges stem…
Why simple language isn’t so simple: the struggle to create plain language in documentation
Jul 27, 2017 • 30 min
Although you can adjust your content’s style to be simpler and more readable, technical documentation introduces many new terms and concepts for readers to learn. Many readers who don’t already understand the discourse community may find this language…
When the pain of ignorance exceeds the pain of learning
Jul 23, 2017 • 17 min
Users turn to documentation when the pain of their ignorance exceeds the pain of learning. Unfortunately, this is the worst state of mind to try to learn anything in. To address this impatient state of mind, we need to write documentation in simpler,…
Transparency in documentation: dealing with limits about what you can and cannot say
Jul 13, 2017 • 18 min
Although traditionally as a technical writer you don’t run into too many ethical scenarios for docs, sometimes you have situations where your ability to be transparent about a system’s limitations gets curtailed by marketing or product management. It can…
Recording of my WTD Portland 2017 presentation on Building navigation for your doc site — 5 best practices
Jun 8, 2017 • 21 min
Here’s the recording of the presentation I gave at the Write the Docs 2017 Portland conference. The presentation explores best practices for doc navigation, including principles such as hierarchy, modularity, progressive disclosure, entry point, and…
Recording of User-Centered Design Principles for Organizing Documentation
Feb 18, 2017 • 57 min
I recently presented to the STC Twin Cities chapter on User-centered Design Principles for Organizing Documentation. When organizing your documentation, such as arranging navigation titles, workflows, or other wayfinding features, you can apply universal…
Recording: Modern Technical Writing, by Andrew Etter (STC Silicon Valley chapter)
Jan 24, 2017 • 62 min
Andrew Etter presented about his book, Modern Technical Writing, to the STC Silicon Valley chapter on January 24, 2017 in Santa Clara, California. In the presentation, Andrew talks about the strategies he implemented at Palantir to change to a new way of…
Recording: Writing tech docs like a hacker with Jekyll
Jan 18, 2017 • 59 min
I recently gave a presentation titled Writing tech docs like a hacker with Jekyll to the to the Southern Ontario STC chapter (on Jan 18, 2017). In the presentation, I introduce reasons why we started using Jekyll, how static site generators differ from…
Recording of Open Authoring — Collaboration Across Disciplines presentation, by Ralph Squillace
Nov 15, 2016 • 96 min
Ralph Squillace, a senior content engineer for the Microsoft Azure Infrastructure team based in San Francisco, California, recently gave a presentation to the STC Silicon Valley chapter (on November 14, 2016) on Open Authoring — Collaboration Across…
Saving Your Sanity Through Better Client Relations — with Alisa Bonsignore
Oct 18, 2016 • 55 min
In this presentation, Alisa Bonsignore, a technical communication consultant based in the San Francisco Bay area, talks about how she developed confidence and experience in consulting with clients about writing projects. In the beginning, Alisa started…
How can technical writers thrive in agile environments? Event recording and details
Sep 20, 2016 • 65 min
Last Monday we had a record turnout at our STC Silicon Valley chapter (with about 40 attendees). The topic was a panel discussion on how to thrive in agile environments as a technical writer. With 5 panelists all from different companies, the perspectives…
Balancing the never-ending list of documentation to write with your natural interests and passions
Sep 2, 2016 • 11 min
Sometimes I think that I’ve covered every possible topic on this blog that is possible to write about, and my muse becomes silent for a while. But then I remember the purpose of the blog — to be a web-based log, or journal — and I realize that the only…
Recording of Let’s Tell a Story — Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)
Sep 2, 2016 • 55 min
Matt Ness, a technical writer at Splunk and a co-organizer for WTD San Francisco, recently gave a presentation to the STC Silicon Valley chapter called Let’s Tell a Story: Scenario-Based Documentation. In this presentation, Matt talks about ways to…
Presentation recording: Hunting for API developer documentation jobs in the San Francisco Bay area, by Andrew Davis
Aug 15, 2016 • 73 min
Andrew Davis recently gave a presentation on finding developer documentation jobs (mostly for API documentation) in the San Francisco Bay area. The title of the presentation is Hunting for Dev Doc Work around the Bay. You can listen to the presentation…
The complexities of translation and the need for dynamic variables in the build process
Aug 15, 2016 • 14 min
Translation is a complex undertaking that usually requires you to take advantage of dynamic variables and other parameters in your source format in order to generate out different languages. Although most people think of static site generators as…
The Story of Paligo: A new browser-based CCMS with all the features you’d ever want
Aug 1, 2016 • 8 min
Up until two years ago, Anders Svensson and his colleagues, based in Sweden, provided DITA and XML consulting. They eventually created their own XML-based component content management system (CCMS) called Paligo, which includes a full set of documentation…
Will the docs-as-code approach scale? Responding to comments on my Review of Modern Technical Writing
Aug 1, 2016 • 16 min
My previous post reviewing Andrew Etter’s ebook on Modern Technical Writing got an enormous response. Some readers said the docs-as-code approach works only for small shops and doesn’t scale to large projects. They said content re-use and translation also…
Review of Andrew Etter’s ebook on Modern Technical Writing
Jul 26, 2016 • 10 min
In Modern Technical Writing: An Introduction to Software Documentation, which is an e-book you can read on your Kindle, Andrew Etter argues for a model of technical writing that involves lightweight markup languages (like AsciiDoc and Markdown), static…
Applying Tim Ferriss’ 4-hour work week rules to tech comm projects
Jul 20, 2016 • 9 min
Principles in Tim Ferriss’ book The 4-Hour Work Week can be applied to tech comm projects. By focusing on the 20% of tasks that result in 80% of the results, limiting your focus to two mission critical tasks a day, empowering those around you to make…
Thoughts on Transforming Documentation Processes presentation at WTD: Evaluating the trend to treat documentation as code
Jul 15, 2016 • 9 min
At the last Write the Docs conference, Riona Macnamara, a tech writer working on internal developer documentation at Google, moderated a panel about transforming your documentation process. The panel consisted of four writers from various companies —…
Context switching and efficiency — Kanban to the rescue?
Jul 13, 2016 • 7 min
In Become More Productive and Motivated, Mattias Sander provides a well-written overview of Lean, which is a strategy for eliminating waste and focusing more on customer value. What interests me most with Sander’s discussion about Lean is…
Why Programming Sucks and the fallacy of documentation in the context of code chaos
Jul 12, 2016 • 7 min
Yesterday on Write the Docs, someone shared an article titled Programming Sucks, by Peter Welch. More than just a developer monologue, this article seems to hit on universal truths about programming, so much so that the article has been translated into 10…
Thoughts on Documentation Avoidance for Programmers
Jul 9, 2016 • 6 min
This past week on the Write the Docs forum, there was a bit of discussion around a recent presentation titled Documentation Avoidance for Programmers. In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing…
Presentation recording: Move Fast And … Document Things? Lessons learned in building documentation culture at a startup, by Ruthie Bendor
May 22, 2016 • 35 min
During the May WTD meetup, Ruthie Bendor, a web engineer, gave a presentation titled Move Fast And … Document Things? Lessons learned in building documentation culture at a startup. This post contains the audio and video recording of her presentation.
Recording of Version Control, Writers, and Worfklows by Richard Mateosian
Dec 17, 2015 • 63 min
You can watch the recording of Richard Mateosian’s November 2015 presentation to the STC Silicon Valley about version control, writers, and workflows.
Podcast: Spec-driven Development of REST APIs, with a focus on RAML — interview with Michael Stowe
Oct 12, 2015 • 45 min
Spec-driven development is an approach to developing REST APIs by first describing and prototyping the API through a specification file (such as RAML or Swagger), and then coding the API. The spec not only serves as a contract for the API’s development,…
Udemy podcast (with me) and infographic on technical writing
Oct 6, 2015 • 38 min
Recently I was interviewed by Alex Bankoff from Udemy for a podcast on the field of technical writing. The Udemy team also created an infographic about the topics covered in the podcast.
Podcast: The divide between academics and practitioners — Interview with Lisa Meloncon
Aug 10, 2015 • 57 min
In this podcast, I talk with Lisa Meloncon, an associate professor at the University of Cincinnatti, about the academic-practitioner divide.
Podcast: How do design, length, and relevance affect how people use API reference docs — interview with Bob Watson
Jul 30, 2015 • 52 min
Bob Watson recently finished a PhD with research that examined how the design and content of API reference docs affects the user’s performance. In this podcast, I talk with Bob about his findings and his other research interests, primarily around goal…
The key to writing good documentation: Testing your instructions
Jul 7, 2015 • 23 min
Writing good documentation requires you to set up a test environment and test all of your instructions — testing the instructions yourself and against a user. Testing instructions can be time consuming and tricky, especially with developer documentation.…
API Documentation presentation to East Bay STC chapter — slides and recording
May 16, 2015 • 60 min
The other week I gave a introductory presentation on API documentation to the East Bay STC chapter in Silicon Valley. Here are the slides and recording.