Broadcasting your meeting notes (API documentation topic)

A few months ago I added a topic to my API doc course called Sending doc status reports – a tool for visibility and relationship building. Another tool for accomplishing a similar purpose -- that of making others in your company aware of documentation processes, newly published articles, how to work with your team, etc. -- is to broadcast your meeting notes after each meeting. Although sharing meeting notes with meeting participants after the meeting isn’t anything new, with a few small adjustments, it can be a powerful way to influence those around you. Read more here: Broadcasting your meeting notes to influence a wider audience.

Barefoot shoes, basketball, and how to avoid recurring calf strains

This post is mostly about shoes (and the way the shoe industry has gone awry), but it's not entirely unrelated to technical writing (which is the usual focus of this blog). Technical writing is a sedentary career that involves sitting all day. In this sedentary mode, it's easy to develop bad posture and other physical problems. At any rate, almost all of us have physical ailments of some kind, especially related to our feet, knees, and back. In this post, I argue that shoes with elevated/wedged heels might be partly to blame. Elevated/wedged heel shoes shorten and atrophy our calf muscles and imbalance our posture, leading to back pain, strained calves, and other issues. I share my story of why I got into wearing barefoot shoes and how I've reconciled natural movement with basketball playing.

"The writing process"-- a new section in my API doc course

I added a new section to my API documentation course on the writing process. The section has six new pages and includes tips on moving through the writing process from beginning to end.

HastyDocs: A new approach to keeping API documentation up-to-date, by Jarek Piotrowski

The following is a guest post by Jarek Piotrowski, co-founder of HastyDocs. HastyDocs is a new tool that allows you to associate files in your codebase with your more conceptual Markdown files. You then receive updates when the code changes. (Note: This isn't a sponsored post — I thought this would be an interesting, relevant tool for the API doc community.)

Urban sprawl and car dependence -- some thoughts on solutions

In a recent post I wrote about commuting strategies, reflecting on first- and last-mile strategies for commutes. This week is also the UN Climate Change Summit. In keeping with these themes, I want to address the topic of urban sprawl. When I moved to the Seattle area last winter and was looking for housing, I explored about half a dozen different areas, including downtown areas as well as bedroom communities. I found the downtown areas cramped, expensive, and small, especially for a family of six with a minivan. As a result, we chose a bedroom community (Renton, which is 20 miles south of Seattle), but now I've learned that I'm actually promoting urban sprawl, which has a long list of ugly environmental, social, and financial impacts, the most depressing being the lock-in to a car-dependent world.

Write the Docs Podcast Episode 35: Docs for Developers book, with Jared Bhatti and Zachary Sarah Corleissen

In episode 35 of the Write the Docs podcast, we discuss the newly released book Docs for Developers: An Engineer's Field Guide to Technical Writing with Jared Bhatti, staff technical writer at Google, and Zachary Sarah Corleissen, staff technical writer at Stripe (two of the co-authors). This book on writing documentation focuses on the end-to-end writing process (from audience analysis to drafting, editing, publishing, and more) and is written specifically with developers in mind. The authors use the scenario of documenting Corg.ly, an API that translates barks, as a common thread through each of the chapters.

Presentation recording -- 'Best practices in API docs: Product overviews and getting started tutorials'

I recently gave an online presentation about product overviews and getting started tutorials in API docs, sponsored by the STC Washington, D.C.-Baltimore Chapter. This post provides a recording of the presentation and related details.

The existentialism of technical writing

Every now and then I catch myself wondering about the docs I wrote at my old job, looking to see if there has been new content added to the site, any radical redesigns or restructurings, any new doc themes or apparent moves. I’m not sure why I occasionally look, other than mild curiosity, but it’s led me to wonder about my future as well. What seems so important and urgent now is on a countdown timer. No matter what content I’m working on, give it a few years, and this content will probably go the same way, becoming neglected, slowly rotting away and becoming less relevant, less accurate, less needed. Some other writer will inherit the content and wonder about its history or even if it’s needed. The upcoming months will slowly wash the content away, until someone eventually deletes the page.

New article in API doc course: Using Oxygen XML in docs-as-code workflows

I added a new article in my API doc course about how to use Oxygen XML in a docs-as-code workflow. Oxygen XML is a robust authoring and publishing tool for technical content that allows you to author in multiple formats (Markdown, HTML, or XML) as well as publish to multiple outputs (HTML-based webhelp, PDF, and more). Although traditionally used for XML authoring and publishing, Oxygen XML has expanded its support with Markdown files, especially with the DITA's recent support for Lightweight Markdown. In this new article, you'll learn more about Oxygen XML, different workflows you can use to publish in a docs-as-code model, Git integration with Oxygen XML, supported Markdown formats, how to get started, and more. (Note that this is a sponsored post.) Read more here: Using Oxygen XML with docs-as-code workflows.

Biking and public transportation in Renton and Seattle: Solving the first-mile and last-mile problems

Last month I wrote a post about returning to normal, and as part of that return, I wanted to commute to work. Part of why I like the commute is because for the past decade, I'd been biking to work. That biking window provided me with a built-in time for daily exercise, and I also liked the space to wind up and wind down for the day. When I lived in California, I was fortunate enough to live next to a paved trail (following a canal) that took me 75% of the way to work; the remaining 25% was along a road with a bike shoulder, and only 5% on a treacherous road (which has since been fixed for cyclists). But biking to work from Renton to Seattle is a different problem to solve. In this post, I'll talk about strategies for the first mile (getting to the transit hub) and the last mile (getting from the transit endpoint to your actual destination). Even though this post will have specifics about my area, the same struggle likely exists for anyone trying to bike to work in any city.

tcworld China 2021 keynote: 'Tech comm and marketing: How to make your tech comm group more visible to those within your company'

I recently gave a keynote presentation at tcworld China 2021 on the topic of tech comm and marketing. This post provides a recording of the presentation, slides, and detailed notes for the presentation.

New article in API doc course: 'Ensuring documentation coverage with each software release'

I added a new article in my API doc course called Ensuring documentation coverage with each software release. Getting a good handle on your release process -- such as understanding the cadence of releases, how features are tracked and tagged in different phases, and other checkpoints prior to the release signoff -- is central to thriving in any documentation role. Providing doc coverage for each release ensures you don't accrue documentation debt, and it boosts user satisfaction for the new features being released. This article adds to about a dozen other process-oriented articles in the processes and methodology section.

Sending doc status reports -- a tool for visibility and relationship building [API doc course]

I recently added an article titled Processes for reporting status to business stakeholders to my API course. Sending documentation status reports can help foster trust and awareness with your business stakeholders. These stakeholders might be the core leadership within your organization or simply your management chain the next level up. Besides building visibility and relationships with these stakeholders, creating these status reports each month gives you a regular cadence for doc assessment and analysis, which is also helpful.

Recording of 'Product overviews vs. getting started tutorials: striking a balance between read-first and try-first user behaviors'

I recently gave a webinar to tekom Europe about product overviews and getting started tutorials. The recording and slides are below.

Review of "Hashtag #TechComm: An Overview of Members, Networks, and Themes from 2016-2019"

In Hashtag #TechComm: An Overview of Members, Networks, and Themes from 2016-2019, published in Technical Communication Journal (68.2 May 2021), Chris Lam identifies trends and themes in the tech comm field by looking 75,000+ tweets that used the hashtag #techcomm from 2016 to 2019. Previously, academics looked at job advertisements to identify trends, so this Twitter analysis for data provides a new approach to identifying trends.