In the previous post, I debated about the type of content that engages an audience versus the type of content engages the writer. I said the thinking/writing process is probably more valuable than the subject, but also that the subject should be something you, the writer, should be naturally drawn to because you'll be most productive being in that space. At the same time, if you want to engage a particular audience, you need to find topics that both you and the audience resonate with, which might be challenging. In this section, I'll get a little more down-to-earth about my audience and focus.
In the previous post, I explained some web fundamentals, such as having a website, learning SEO, capturing subscribers to your newsletter, and so on. However, given that documentation reports and meeting notes failed to engage my readers, I wondered about the key ingredient to influence: engaging content. What types of content would readers find engaging? This turns out to be a complex question with no easy answer other than to focus on what engages you and hope that someone else has a mutual interest. The problem is that those with a mutual interest are likely outside the target business audience.
In the previous post, I explained how email fails as a communication channel in the workplace, and how solely relying on email-based content can cause you to miss out on my analytics and other common web techniques. In this post, I'll look at a few aspects related to content production on the web. Although these techniques all seem basic, hardly any of them are followed in the workplace.
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.
