Write the Docs Podcast Episode 34: Adding personality to documentation, with Fabrizio Ferri

In this podcast, Fabrizio Ferri joins us for a discussion about adding both personal identity and personality to documentation. Why are the docs we write so often anonymous, and does that anonymity work against career progression? Are tech writers, typically introverts, averse to publicity, or does our industry not allow for it? And if you want to be a "personality" in the tech communications world, what do you do? How do you add personality constructively to your work without disrupting corporate brand and consistency?

Five project management responsibilities of senior technical writers

Last week I wrote a post about ambiguous content and how one aspect of being a senior tech writer is taking on more ambiguous projects. In this post, I want to continue this thread on what it means to be a senior tech writer, or even a lead technical writer. But rather than exploring ambiguous content, senior/lead tech writers also have a lot more project/program management responsibilities as well. There are at least five key responsibilities I'll explore here: prioritizing work, defining doc strategies, organizing work among multiple writers, reviewing contributions, and reporting upward.

Trying to get back to normal

As the pandemic winds down in the US, I've been trying to get back to normal. I've been especially motivated to find this normal because I made both a job transition and a home relocation during the pandemic, so I don't have the context of what normal even looks and feels like. I can't "return to my workplace" because I'd never seen my new workplace. I don't dread the commute because I'd never made the commute (from my new home). Since moving to Renton, which is 30 minutes below Seattle, my experience has mostly been within the walls of our home and the green woods here. So for the past couple of weeks, I've set about experimenting with several ways to return to normal. In doing so, I've been surprised by how much I've forgotten.

Paligo: Structured Authoring and Component Content Management made easy

Paligo is an online XML-based CCMS for authoring teams that are either looking to level up from help authoring tools to robust structured authoring and component content management, or for teams that want to escape the complexity and cost of their legacy CCMS. Paligo simplifies structured authoring with a visual interface that teams can access through an online portal. In this post, I explain Paligo's context within the CCMS landscape, how it's different from HAT tools, and why it's a documentation solution worth considering for both enterprises and small businesses.

Experiments: Leaving reviews on Google Maps

A few months ago, I decided to start leaving reviews on Google Maps of nearly every place I visited. The result has made me feel more empowered.

10 characteristics of ambiguous content

As a senior technical writer, part of my job description is to focus on tackling "ambiguous" content, as opposed to more straightforward content that is more commonly assigned to non-senior technical writers. At first, I wasn't entirely sure what "ambiguous content" meant (that fuzziness is part of its definition), but this has come into focus more over the past few months. Here I'd like to describe what ambiguous content means, as it helps identify content that has characteristics I've encountered for years.

Experiments: Will reading a physical newspaper improve the way I consume news?
Experiments: Will reading a physical newspaper improve the way I consume news?

Lately I've been trying trying something that I call life experiments. These are goals that I adopt for about 50 days and then evaluate their impact on my life. With this experiment, I decided to stop reading the news on my phone and to instead read a physical newspaper delivered to my house each day.

Experiments: What would happen if I exercised 2 hours a day?
Experiments: What would happen if I exercised 2 hours a day?

Lately I've been trying trying something that I call life experiments. These are goals that I adopt for about 50 days and then evaluate their impact on my life. The reason for 50 days is to give the experiment sufficient time to have had an impact. If I keep an experiment for a week or two only, it's hard to see what change it makes. So far, my first life experiment — exercising two hours a day — has been been an interesting one.

Balancing action with narration: Creating product overviews and getting started tutorials to satisfy both try-first and read-first learning modes

This is an abstract for a presentation that I'm thinking about creating. In a nutshell, the presentation focuses on finding the right balance between action-oriented task writing and big picture narrative product overviews — both of which seem to be opposing but complementary content types in technical communication. I'm floating this presentation draft here to gather feedback and refine the direction a bit more.

An in-depth look at MadCap Flare 2021’s New Markdown Import Feature
An in-depth look at MadCap Flare 2021’s New Markdown Import Feature

MadCap Flare’s first major new release of 2021 includes, among other new features, the ability to import Markdown files. There are several workflows where this Markdown import could be useful, most notably in scenarios where tech writers support multiple engineering teams that author READMEs and other how-to content in code repos.

Finding a focus

I've been trying to think of a good focus for upcoming presentations and my blog lately, but I'm unsure about topics. I've focused on many topics in the past: trends, API documentation, docs-as-code tools, and before this, other areas such as blogging, podcasting, quick reference guides, value arguments, visuals, user-centered docs, and more. Ideally, I'd like to turn over a new leaf with some engaging topic that I've never explored before, but I'm not sure what that would be.

Updated API Getting Started tutorial

I updated the Getting Started tutorial section in my API course. I included a new section about the philosophic foundations of getting started tutorials, as I believe that this mindset toward action-oriented learning in API documentation is key. I also realized that the Run in Postman buttons are now forked collections in a web interface rather than static code that is downloaded to a local Postman client. So much changes in API tools that from one year to the next, any tutorial is sure to become outdated.

Technical writing course Q&A -- 'Become a Technical Writer', with Bobby Kennedy

Technical writing courses are popular ways for people transitioning into technical writing careers to build their skills, become familiar with the technical writing profession, and ultimately transition into jobs as technical writers. I had a chance to chat with Bobby Kennedy, a professional technical writer based in New York, who recently created a technical writing course called Become a Technical Writer.

Updated Stoplight tutorial

I updated (almost entirely rewrote) the tutorial for using Stoplight Studio. This is one of the centerpieces in my API doc course because it provides an easy way to create an OpenAPI specification document, without having to be familiar with the OpenAPI syntax or YAML.

Switching from Skype to Zoom for podcasting tools

I'm switching from Skype to Zoom for podcasting tools. Skype seems to be part of another era. The switch to Zoom opens up opportunities for another type of content -- one where participants share their screen more.

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.