Themes from 2021: working from home and podcasting
Many themes surfaced in 2021, but I want to address two: working from home and podcasting.
Site analytics for 2021 -- a few observations and reflections
I updated my site analytics page for 2021. As far as noteworthy metrics, not much that has changed, but there are a few small trends worth reflecting on.
PDF and eBook formats available for API doc course
PDF and eBook formats are now available for my API doc course. People have long-requested these formats, and I finally decided to create and make them available.
Upcoming presentation for Megacomm: How to increase awareness of tech comm inside corporate walls
I'm giving a presentation called How to increase awareness of tech comm inside corporate walls in February 2022 at the Megacomm conference, which is a conference for tech comm professionals in Israel. (This year's conference will be a hybrid of online and in-person events.) A description of my presentation is below.
One year later after moving to Seattle
A few people have asked me how I like Seattle and how things are going after the move. Given that it's been a year since we moved to Seattle, I thought this would be a good topic to write about. Overall, the move was a good decision, and we've all adjusted well. As I head into the next year, one thing that concerns me is that I've been writing less, so in 2022 I plan to rekindle that energy.
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.
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.