In my previous post, I explained that anyone can create content and broadcast it on the web, gathering up an audience and building a reputation of expertise. I wondered if these techniques could be implemented in the workplace. In my initial attempt to create content in the workplace, I focused on two efforts: (1) creating documentation reports and (2) sharing meeting notes. The efforts sort of failed because I neglected some web fundamentals.
This is a multi-post series exploring a hypothesis about influence on the web and in the workplace. The main question I'm exploring is whether the same techniques for visibility and influence on the web can have a similar effect within the workplace, which has different dynamics, cultures, tools, and expectations.
Many themes surfaced in 2021, but I want to address two: working from home and podcasting.
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 are now available for my API doc course. People have long-requested these formats, and I finally decided to create and make them available.
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.
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.
