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.
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.
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.
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.)
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.
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.
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.
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.
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.
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.
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.
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.
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.
I recently gave a webinar to tekom Europe about product overviews and getting started tutorials. The recording and slides are below.
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.
