Connecting micro content with search analytics -- notes on the first MadCap Flare and MadCap Central 2020 Release
MadCap Software's 2020 release for MadCap Flare and MadCap Central include significant enhancements to micro content, code syntax highlighting, privatized output, and more. Through search analytics in MadCap Central, if you identify search phrases, and search phrases that return no results, micro content can be created to address these gaps, making your content much more discoverable for your users.
A user manual for your death?
This is a gloomy topic but one that until recently I'd never even considered. When you die, what "user manual" will your family members follow to carry out tasks that need to be done? About two years ago my father passed away, and while it was emotionally difficult, I realized that figuring out the logistics of one's passing was also challenging. In preparing for the worst with the Coronavirus, I started to think about what needs to be done in case I die. (Of course, I hope this doesn't happen, and I'm not sick or anything. I'm just thinking ahead to worst-case scenarios.)
API doc course update: Re-architecting the OpenAPI spec tutorials to start with visual modeling tools first, then code
One of the most challenging aspects of my API documentation course is with the OpenAPI specification. Describing how to code this detailed spec line-by-line is not only tedious but highly prone to error, confusion, and frustration. Recently, I decided to shift the approach in my course to begin first with coding the OpenAPI spec in a visual editor using Stoplight Studio, and then later, if desired, transition to a code-based approach.
My Knowledgebase Ninjas podcast episode -- "Metrics don't work"
I recently appeared on the Knowledgebase Ninjas podcast in an episode titled Metrics Don't Work. In the podcast, I chat with Gowri Ramkumar about documentation processes, why metrics are problematic, advantages and disadvantages of docs-as-code models, why measuring doc traffic falls short, the value of internal documentation, people I've learned from in my career, advice for my younger self, and more.
API The Docs Virtual Series 2020 -- Upcoming presentations and thoughts on the virtual format
I'm giving a presentation on May 27 in the API The Docs Virtual series titled How Trends in API Documentation Differ from Other Tech Comm Trends. You can register for free on EventBrite. API The Docs is typically a one-day conference event but has gone virtual and is experimenting with different formats in interesting ways. In this post, I also share a few thoughts on the first virtual sessions and the challenges of finding the right online format for conferences.
WTD Episode 29: Salary Survey results and WFH tips, with Eric Holscher
In this episode, we chat with Eric Holscher, co-founder of both Read the Docs and Write the Docs, about the recent Salary Survey that the WTD group conducted. This survey was launched in Fall 2019, and the results published were recently published. The salary survey covers details such as types of employment, job titles, roles, length of time in role, work location, annual salary, salary breakdowns by state, additional benefits, satisfaction, reasons for dissastisfaction, organization type, respondent demographics, and more. In addition to exploring the survey, we also chat about tips for working from home, especially given that both Eric and Chris have been working remotely for many years.
Are technical writers increasingly playing non-technical roles? Some thoughts on the evolution of technical writing roles
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 different job categories. In some scenarios, writing might never have been why we were hired.
Podcast: Users as producers of knowledge — conversation with Nupoor Ranade about how tech writer roles are changing
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 for passive users, users are actively directing and shaping the knowledge that writers produce. In this podcast, we look at ways docs-as-code workflows are facilitating that shift in roles. This podcast is more of a conversation, where I first ask Nupoor a series of questions, and then she asks me questions. There's also a transcript of the podcast.
Staying updated about what developers are changing -- my techniques for information sleuthing
In an ideal world, developers include technical writers in all relevant meetings and keep them updated about changes they're making that might affect the docs. If this is the case for you, count yourself lucky. More often than not, however, technical writers are left out of the loop until the last minute, when someone remembers that the docs likely need to be updated (or should have been updated prior to release). This scenario is just as true whether everyone is working from home or in the office. One solution for this is to embrace a technique for information sleuthing.
UX writing processes and considerations -- WTD podcast episode 28
Write the Docs podcast episode 28 is a recording of a Berlin WTD meetup focused on UX writing processes and considerations. The event was live streamed on March 9, 2020 at the Humanitec in Berlin by Chris Ward.
Tech comm podcasts are growing -- here's a list
Podcasts seem to be growing now more than ever. Here's a list of more than ten technical writing podcasts that you can listen to.
Life on reset -- new dynamics emerging
With the shift to sheltering in place and working from home, I've noticed that my family has grown closer together and that working remotely goes better when everyone is also remote.
Working from home — things I've bought
Now that most of us are working from home, I thought I might write a post about things I've bought in an effort to be more comfortable and productive in wfh mode.
How life has changed with the pandemic
These past two weeks have been incredibly disruptive in terms of world events, and while I usually avoid writing about current events and tend to stay within the tech comm focus, it seems like ignoring the elephant in the room not to mention something about the Coronavirus pandemic.
Webinar recording: How Trends in API Documentation Differ from other Tech Comm Trends
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 available below.