Barefoot shoes, basketball, and a possible fix for 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 wedged heels might be partly to blame. 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.
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.
New sections in API doc course exploring causes for poor product overviews and getting started tutorials
I added two new sections in my API doc course exploring reasons for poor product overviews and sometimes absent getting started tutorials. I'm still adding to this section but wanted to share the current content. These are all first drafts that I hope to refine a bit with more imagery, proofreading, examples, and other detail, so if you have feedback, let me know in the comments. I'm trying to explore reasons why these two content types often fail or are weak. It's less of a best practices section and more like an analysis about causes.
Five basketball strategies and how they might apply to tech comm
Because it's NBA championship finals time, I thought it might be fun to write a basketball-themed post focusing on basketball strategies that succeeded or failed, and how any of these strategies might apply to technical writing. Beyond the specifics of any particular strategy, the larger application to tech comm is to simply formulate a strategy, to think strategically about how to "win" at technical writing. With that, let's jump into five basketball strategies.