I'd Rather Be Writing Podcast Feed

About the Symposium for Communicating Complex Information You can view the conference program and schedule for the Symposium for Communicating Complex Information here. My presentation on trends My presentation was a keynote on tech comm trends called Tech Comm Trends: Providing Value as a Generalist in a Sea of Specialists. You can view my slides at trends-growing-disproportions. The recording of my presentation is available here: If you just want to listen to the audio, you can listen here: Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Latest thoughts on trends Although I’ve written and spoken about trends several times this year, I shifted focuses a bit in this presentation. I abandon the argument that technical skills are in such high demand because the technology landscape is getting more complex. (It might be true, but it’s a hard argument to make, and I’m not so sure about it anymore given some responses in my ongoing Engineers writing docs survey.) Instead, I argue that technical writers are supporting increasing numbers of engineers. I dig out more specific employment data from the BLS showing that the job growth between 2010 to 2016 for software developers was 37%, but for technical writers was just 6%. Additionally, in informal surveys, 76% of tech writers agree that the ratio between engineers and tech writers is getting more lopsided each year in favor of engineers. Together, this data presents an alarming trend where tech writers are becoming dwarfed by the explosion of engineers. This trend also aligns with my own experiences in the workplace where I seem to be getting spread thinner and thinner. What happens when tech writers must suddenly start supporting twice the number of engineers or more? First, I think tech writers will play more project management roles, orchestrating publishing workflows for other authors, including engineers. Engineers who contribute to docs are also much more likely to use docs-as-code tooling and workflows, which is a direction that my Engineers writing docs survey survey seems to confirm so far. The other consequence of supporting more engineers is that it dilutes the tech writer’s ability to immerse deeply on a project. If you were supporting 3 engineering teams last year, and this year you’re supporting 4, and next year you support 5, you don’t have the same bandwidth to fully immerse in the project’s technology, team, tools, and other information needs. You end up being even more of an outsider and novice to the technology, which cripples your ability to create more in-depth, comprehensive content. To counteract this trend toward the dilution of tech knowledge, I think tech writers need to more purposefully study and dive into tech learning, even at the expense of some writing productivity. In almost all tech writer job requirements, the demand for strong technical knowledge continues to be a key requirement — one that over overshadows one’s writing ability. Feedback in surveys provides a lot of insight that helps me refine my thoughts about directions with trends. I know I’ve written about this topic extensively this year, and with each iteration, I’ve been collecting feedback and refining my ideas. This iteration shows another adjustment. The Q&A after my presentation gave me good feedback about further refinements and modifications for my presentation on trends. For example, conference attendees wondered whether the disparity might be explained by increases in tech writers offshore (outside the BLS data), the diversity of tech comm job titles, the increase in user-generated content, and other factors.

This week I traveled to Louisiana to attend the Symposium for Communicating Complex Information and presented on tech comm trends. You can listen to the recording, view my slides, and read my latest thoughts on trends here.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Background The term “10X engineer” (pronounced 10-ex) is sometimes used to describe engineers who are ten times more productive than other engineers. It describes someone who is simply more efficient, capable, and accomplishes more than others. The Silicon Valley Dictionary explains: “10X-engineer”: A concept sometimes used in Silicon Valley to describe an engineer that is 10X more productive than an average engineer although the 10X metric is figurative. Sometimes referred to as “Ninjas”, these engineers are highly sought after by all tech companies Jim: You gave me 100 resumes but none of these guys are 10X engineers. Why hire a few of these guys to slow us down when a 10X engineer is so much more productive? For more on this term, see 10X Engineer Series. What has prompted my interest in becoming a 10X technical writer? Well, lately I feel like I’ve let my edge slip a bit at work. I don’t feel as influential and effective in the workplace as I feel online through my blog and podcast. I’ll return to this idea a bit later in this post (in Tip #5), but to get moving towards the 10X goal, let me throw out a few simple strategies first. (Note: In an earlier version of this post, I used the term “rock star” instead of 10X, but some commenters pointed out that “rock star” is a gendered term that is somewhat problematic. I like 10X better anyway, as it more closely gets to my larger desire, which is increased productivity, not increased notoriety. In the revision of this post, I expanded the content in many places, approximately doubling the length and replacing a tip.) Tip #1: Record your meetings with engineers to listen again later With developer doc projects, engineers can quickly jump into excessive jargon and assumptions about your technical knowledge and familiarity with the code. This can be like a firehose of information that is too overwhelming to comprehend fully at the time (at least not to the extent that one can write documentation). If you can’t absorb the information in the meeting, you might need to set up multiple meetings with engineers, tiring their patience. Or you might need to rack your brain for all the details that you’ve forgotten. Or take up study of the topic on your own. What’s the solution for more productive meetings with engineers? Record the meetings! When I record meetings with engineers, I can go back over what they say numerous times and slowly piece the details together. Most online meeting tools (e.g, Chime) have a record function, and in-person meeting tools like Evernote also provide recording capabilities built in to the editor. If I have to delay a project for a while, having the recording to listen to allows me to refresh my memory perfectly even after weeks of focusing on other projects. Almost no one objects to being recorded, and when I produce documentation that recalls all the details at a perfectly granular level, SMEs are really impressed. I remember one meeting I had with a PM at a gamification startup company. The PM (a former engineer) outlined a complicated technical concept that was over my head at the time. But I recorded it with Evernote. All I needed to do was write a one page doc topic. I leveraged the recording quickly to generate the doc — getting the technical terms and phrases just right. The PM was impressed at how accurate and on-target the doc was — from just one short meeting. Ideally, I’d like to get more expert at pulling information out of engineers’ heads similar to how storyteller podcasters (e.g., Ira Glass with This American Life) can pull information out of interviewees in a story format. Theoretically, all the needed technical knowledge is inside the engineer’s head, but it often comes out in random structures and tangents. I want to learn to shape and control that information so that essentially I can just clean up my recorded notes and turn them into documen

How do you become a 10X technical writer in the workplace (10X means 10 times more efficient and productive than others)? In this post, I raise the question and then offer a few tips I try to follow: (1) Record your meetings with engineers, (2) Respond quickly to emails and messages, (3) Iterate on content with ever-expanding layers of reviewers, (4) Put some work back on those who request it, and (5) Learn to say no so you can focus on fewer projects with deeper engagement.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Our original feedback form A few months ago, we added a feedback form to our Appstore docs at work. Right below the title on every page, we added an easily visible button that says “Submit Feedback.” The button opens a Qualtrics form where users can submit ratings and comments. This initial feedback form looked like this: Not a lot of feedback came in through this form — maybe one legitimate comment a day on average. Our metrics say about a thousand people visit the docs a day, so why weren’t more people leaving feedback? I doubted they were all finding exactly what they needed and leaving happy and satisfied. Designing for feedback I wanted to tweak my feedback form to maximize the number of responses. I considered questions like these: What factors influence whether users decide to leave feedback? Are there design implementations that might double or triple the responses? How could we ramp up the percentage of people who leave feedback? I was reading some research by Donal Kavanagh on this subject. Kavanagh is a student in an MA program at the University of Limerick (Ireland). I’ll publish a lengthy guest post from him next week (stay tuned). One point in his research is that users are more apt to provide feedback if they feel their feedback is listened to and acted upon. Donal writes, … a feedback feature should engender in the user the belief that their feedback will be acted upon. … A lack of acknowledgement of users’ feedback and even less communication as to how it will be used to improve documentation mean that users will not believe that their feedback is valued and will not understand their place in a process that is ultimately for their benefit, i.e. the continuous improvement of the online help. In other words, the more users feel that their feedback is listened to and acted upon, the more likely users are to give feedback. This point hardly needs to be argued, as we confirm this principle in our everyday conversations. If someone is really listening, we talk confidently and openly. If someone doesn’t seem to be paying attention, our motivation to keep talking fizzles. I realized our original feedback form didn’t have a contact email address for users to optionally list their email. I had omitted it, thinking that PII (personally identifiable information) forbid it. But after consulting with our Legal department, I receive the go-ahead, so long as we didn’t store any email addresses longer than two years. I also decided to adjust a few of the questions to align with AWS’s feedback form (here’s an example). Our revised feedback form now looks like this: Adding this contact email field makes a significant difference because it invites a conversation. It indicates that we are listening and will potentially respond. Another challenge was to address the response time. In our original feedback form, we had to go to the Qualtrics site (which is a survey tool) and check to see if any responses had come in. But we checked Qualtrics only once or twice a week, so this probably gave users the impression that their feedback fell into a black hole. I added a trigger in Qualtrics to push the survey response to my email as soon as it was received. Now when we receive comments, we can immediately email the user with any follow-up questions, or even just to let them know we received their email. I’ve found that catching the user in the moment they have feedback is key to encouraging more detail and elaboration from the user. After the user has moved on (especially beyond 1-2 weeks), their feedback becomes much more general and unspecific. Assessing results I only made these updates a couple of weeks ago, but so far these tweaks are working well. Email that is pushed into my inbox seems to elicit much more prompt action, as it’s like an email awaiting a response. For users who receive a quick reply to their feedback, especially includin

To encourage users to leave more feedback, add a contact email field on your feedback submission form. When you receive feedback, provide a quick response that shows you're listening and taking action on their input.

Every year, when I re-examine my site analytics, I take the time to reflect on trends I’m seeing with traffic to my own site. Not necessarily industry trends, just trends about which topics are popular on my site. Based on these trends, I assess and re-evaluate some of my directions. This year, I found that the increase in traffic on my API documentation site (which accounts for 59% of my overall site traffic) suggests that more engineers are writing docs. This confirms my earlier predictions at the beginning of 2018 that specialization will drive more engineers to write API documentation, with technical writers playing more supporting editorial and publishing roles.

I recently chatted with Ellis Pratt on his Cherryleaf podcast. The episode is called Podcast 49: Should you specialise? Interview with Tom Johnson. We chatted about a whole bunch of topics, not just the should you specialize question in the title. Topics include purposes for writing, the influence of blog...

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. I published the recording of the API documentation workshop that I recently gave in Menlo Park (on Nov 8, 2018). You can view the recordings on my API documentation site here: Recorded Video Presentations. This API documentation workshop (which I mentioned earlier) was a full-day workshop, so there are more than 5 hours of recorded material here. If you’re really into workshop recordings, you can also listen to the Denver API workshop that I gave earlier this year (March 2018). Notes on recording – cardioid versus omnidirectional For the Denver workshop, I used a Movo cardioid lapel mic. However, I think cardioid was the wrong choice because it requires you to have a consistent distance from the mic. When you’re presenting, you might turn your head from side to side or up or down. Cardioid mics are very sensitive to changes in position like this, and the volume fluctuated a lot as a result. Also, the audio sounded flat to me (though I fixed that somewhat in post-production following this technique). For the Menlo Park workshop, I used a Shure omnidirectional lapel mic. Omnidirectional worked a bit better, I think. The sound capture was more of a consistent volume, and my voice didn’t sound as flat. I also applied some post-production enhancements to the audio. However, for video I mistakenly chose to capture the projector rather than my own computer screen, so the resolution isn’t as good as I hoped. Both the Movo and Shure lapel mics have XLR inputs that I attached to a Zoom H4n Pro recorder, which I then put in my pocket (the setup is bulky). The microphone I use to record my blog posts (like this one) is a Shure RE20 cardioid microphone, commonly used in broadcasting. While it is a cardioid microphone, it’s fine because when you’re sitting at a desk recording something, you can keep your mouth a consistent distance to the microphone. And close-up cardioid capture is superior to omnidirectional anyday. Note that in the audio recording of this post, I switched around the various mics so you can actually hear the difference. The Denver API workshop had quite a few views: 2,424 views for Part I, 970 views for Part II, and 433 views for Part III. I expect the Menlo Park API documentation workshop to have similar views, though the view count doesn’t matter too much to me. Why provide free recordings for a paid workshop? As I mentioned in an earlier post (If writing is no longer a marketable skill, what is?), traffic to my API documentation site is now greater than the traffic to my blog. By putting information assets online for free, it adds to content discovery and visits, which in turn attract advertising and other benefits (like speaking engagements or readers for the API doc book I’m working on). I think the way the Write the Docs conference posts video recordings of their events but continues to sell out each year reinforces the fact that people will still come to your event/site even if they can consume the content on YouTube for free. var contents=new Array() contents[0]=' Sponsored message:Over 40,000 API developers use SwaggerHub to design and document APIs with Swagger (OpenAPI). Learn how SwaggerHub can help improve your team’s API documentation workflow. Get started for free.' contents[1]=' Sponsored message:SwaggerHub was built by the team behind Swagger to help organizations collaborate on their API design and documentation from one centralized platform. Find out why SwaggerHub is the platform for design and documenting APIs with Swagger. Get started for free.' contents[2]=' Sponsored message:SwaggerHub brings together all the power of the open source Swagger tooling into one integrated platform for designing and documenting APIs with Swagger (OpenAPI). Get started for free.' contents[3]=' Sponsored message:SwaggerHub is an integrated API design and documentation platform, built for teams to drive consistency and disci

The recording for the full-day API workshop that I recently gave in Menlo Park, California, is now available. This recording provides more than 5 hours of instruction about writing API docs -- for free. I also share some thoughts on cardioid versus omnidirectional microphones, and which is better in a workshop setting. The audio narration of this post switches around the microphones so you can hear the difference.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. You can read the essay here: Principle 11: Be both a generalist and specialist through your technical acuity. How exactly does the topic of being a generalist or specialist tie in with simplifying complexity? Here’s an excerpt: Do technical writers, who are typically only familiar with the subjects we write about, need to become engineer-like specialists, focusing in on a couple of domains in depth, so that we can write, edit, and publish more knowledgeably in these domains? Is specialization the only way to handle complexity? Will I need to become a specialist to survive as a technical writer in the future? Note that this content has undergone multiple iterations: First version Second version Third version In this third version, I expanded the research in places, provided better organization in my analysis, and tried to integrate some more personal stories in places. I also narrated it as a podcast. Overall, this still remains a challenging topic, and the length of the article probably shows. Also, if you’re viewing the essay on my Simplifying Complexity site, you’ll notice that I increased the font a bit. I don’t know if my eyesight is getting worse or what, but while reading it I kept squinting and decided to simply make the text more readable. I feel like I’ve let this essay occupy quite a bit of attention on my blog lately. With each iteration, I’ve gathered feedback from you through surveys and used the information to write the next version. I don’t always push content through multiple revisions like this. Many blog posts are one-and-done efforts. But this particular topic has been the focus of multiple presentations this year, so it receives continual attention and improvements.

In my Simplifying Complexity series, I added a new post called, Principle 11: Be both a generalist and specialist at the same time. I also recorded this essay as a narrated podcast.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Critical inquiry versus vocational knowledge Lately I’ve been thinking about two types of knowledge: intellectual knowledge versus vocational knowledge. Or rather, critical inquiry versus technical how-to. Or theoretical knowledge versus practical knowledge. In short, asking why versus asking how or what. I’m not entirely sure how to characterize the differences, but the difference in focus has contributed to some angst in my tech writing career lately. Rewind a bit to my previous posts on trends (such as this one or this earlier one), and you’ll find that I’ve been wrestling with the question of whether to be a generalist or specialist. Regardless of any generalist/specialist outcomes around research and what employers want, etc., it’s hard to escape this one critical fact: you can’t write without knowledge. Unless you have a more solid technical grounding, you just can’t write much about those topics. Consequently, in order to be a rock star technical writer (rather than just a supporting editor/publisher for SME contributors), you have to move into the technical knowledge domain to some extent. Not necessarily becoming a specialist, but you have to accrue more understanding of the subject than a generalist might have. With this realization, I decided to sink some dedicated time to simply learning tech every day. For a week at work, I decided that I would do 3 tech pomodoros at the start of each day (a pomodoro is a 20 minute session of focused learning — it’s my approach to learning). Given the many interruptions and needed emails to respond to or meetings or fires to extinguish, etc., I often wouldn’t finish my 3 tech pomodoros until noon. After a week of this, I found that my productivity plummeted at work. It seemed I wasn’t accomplishing nearly the same as what I did previously. So I decided to put the tech learning on pause for a bit to catch up and make more progress on some high-priority documentation tasks. I threw myself headlong into documenting what was one of the more challenging tasks on my plate. But as much as I tried, I realized that it was an extremely complicated subject and not one easy to make progress on. Since the requirements document that engineers gave me as a starting point assumed so much technical knowledge already, the documentation was really slow-going. It’s challenging to write documentation for senior level engineers. Moreover, it’s challenging to write about anything when you only have a partial knowledge of. Presumably, the tech pomodoros I was doing should increase my technical knowledge for the needed documentation, right? Well, the plan sounds good in theory but in practice doesn’t always work out. The documentation tasks at work require an advanced level of knowledge, which I can’t just absorb from google searches or other quick tutorials. I need the e-learning courses that build from ground zero and move through novice, then intermediate, and later to more advanced topics. Which brings me back to my dilemma about being a generalist or specialist. In order to accrue the needed knowledge to be productive in authoring content (or even just editing and structuring it), I need to specialize my knowledge a bit more. Trying to write coherently about something I only partially understand is frustrating, though I guess this feeling captures much of the heart of what it means to be a technical writer. Mark Baker explained in a comment on a post about technical acuity that “All professional technical communicators are … by definition, underqualified for the work they are doing. … The best person for each individual job is the one who comes closest the the virtually unattainable combination of rhetorical and technical acuity and knowledge that each individual job requires.” And why are technical writers unqualified? It depends on the level of complexity you’re documenting, for sure. But for deeply c

If we just see our task as documenting solutions that engineers have solved, it removes the creativity and critical thinking dimension from tech comm. The creative dimension in tech comm comes into play as we identify and solve tech comm challenges, such as devising ways to simplify complexity or otherwise improve the user experience.

Now you can listen to the latest narrated post on I'd Rather Be Writing as an Alexa Flash Briefing skill. This means you can listen to my audio content through your Echo device.