I'd Rather Be Writing Podcast Feed

You can watch the episode on the Write the Docs Podcast site. Links When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects Andrewhead.info Andrew Head GitHub Codescoop

You can watch the episode on the Write the Docs Podcast site. Links When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects Andrewhead.info Andrew Head GitHub Codescoop

You can watch the episode on the Write the Docs Podcast site. Links When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects Andrewhead.info Andrew Head GitHub Codescoop

Jacob Moses has a podcast called The Not-Boring Tech Writer. Recently, he interviewed me for an episode titled Skill #26: Getting Started with API Documentation.

In this podcast, I talk about how to deal with project overload, specifically covering strategies to manage tasks. Scrum is one framework for dealing with project work by allowing you to limit the work you have before you in a more systematic way. I also explain the importance of focusing on a project to build up flow and momentum, without always context switching.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. I was reading a post on the technical writing sub-Reddit community about dealing with project overload and thought it would be a good topic for a podcast. The Reddit post is In over my head - service docs, user docs, and localization (requesting advice). In part, the topic resonated with me because I’m sort of overloaded myself right now, so I thought it would be good to think through some of these challenges. In the post, “keyboardqueen90” describes how she’s buried in work, her manager doesn’t understand what she does, others underestimate the time required to write docs, requests for more support fall on deaf ears, she doesn’t have time to ramp up on tools/tech or influence design because the docs fully occupy her time, she lacks any champion or advocate at the leadership level, she’s a team of one, and more. My podcast is short, but here’s an even shorter summary. To manage incoming work, especially when it’s spilling over, you need a system or framework. Kanban is one system that attempts to manage flow by limiting the number of incoming items by a fixed amount. This approach seems sensible but doesn’t entirely work for tech docs because not every task is equal nor requires equal time. Scrum, an agile methodology used by engineers for much the same purpose here, is a more common framework for managing the flow of tasks. I described the process for managing tech docs with Scrum in Following Scrum with documentation projects. In short, with Scrum you start by prioritizing the most important items in your backlog. You assign some of the items to a two-week sprint. You assign only as many items as your sprint capacity can handle. In your sprints, try to mix in some “quick win” tasks that are easy to accomplish (because they take an hour or less) but which might not be high-priority. When people scream at you for docs with deadlines the next day, tell them you’ve assigned the work to an upcoming sprint. This usually appeases them because they know the work has been scheduled. When people realize you have a framework for managing tasks (one that aligns with engineering frameworks), they tend to be more understanding about pushing out timelines. Another consideration, outside of scrum or agile, is to consider flow. If you’re constantly jumping from one task to another, you can’t get into any state of flow with a project, and your efficiency will plummet. I try to devote several days or a week to a single project before switching over to another one. I mentioned some strategies related to context switching in How to avoid inefficiencies even with context switching. If you’re working on a project that you don’t have sufficient time to ramp up on (for example, it requires you to know X technology, but to learn X technology you’d have to spend a week doing tutorials, which would be fine except that the docs for X are due in two days), you can try this simple workaround: Meet with the engineer and ask him or her to explain and demo the task. Record the meeting. Then basically type out the content by listening and re-listening to the recording, shaping and editing it, and then have the engineer review it. Even if many of the details are still murky in your mind and untested, it might be a feasible solution to avoid derailing your focus on the projects that matter to you. Finally, if your mind is tied up with anxiety and can’t focus due to the stress, check out the Calm Meditation app. I’ve done a number of 10-minute meditations here that put me in a more relaxed state, which is kind of essential for entering the more productive mental mindset for writing. For more on this, see this post on Medium: My system for managing overwhelm, anxiety, and stress when work is too difficult. If you have advice for the situation, consider adding it to the comments on the Reddit post, or you can also add them below.

In this podcast, I debunk 10 myths about API documentation. For example, some myths are that only engineers can write API docs, or that you have to write API docs by deciphering an engineer's source code. In this podcast, I go through these myths one by one with discussion and analysis.

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. 10 myths about API documentation Here are the myths I address in the podcast. You must read source code to write docs. You’ll need to extrapolate sample code from one language to create code samples in another. You must be a former engineer to be competitive in the API doc space. Technical writers usually create the reference material (e.g., OpenAPI spec, Javadoc). Almost all job interviewers care about, when it comes to API doc jobs, is technical know-how. Developers can and will write if you implement a docs-as-code process. Because their role aligns with the audience, with API docs, developers are most suited to be the ones writing for other developers. API documentation and developer documentation are synonymous. Docs that look good are good. People will respect you more if the word “writer” isn’t in your job title. In the podcast, I mentioned this NY Times article: In the Salary Race, Engineers Sprint but English Majors Endure. Your Feedback Here’s a short survey to see if you think these myths are generally true or false. (It would be best if you listened to the podcast first.) You can view the ongoing results here. EMBED_PARAMS = {}; EMBED_PARAMS.surveyID =6879040; EMBED_PARAMS.domain ="//www.questionpro.com"; EMBED_PARAMS.src ="//www.questionpro.com/a/TakeSurvey?tt=WStg1A8jzgU%3D"; EMBED_PARAMS.width ="100%"; EMBED_PARAMS.height = "1200px"; EMBED_PARAMS.border = "hidden"; 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 discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i

Video Audio Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Slides Presentation description Tech comm trends: Providing value as a generalist in a sea of specialists Trends in technical communication can be hard to decipher, even when looking at data. But one underlying trend is that technology seems to be getting more specialized and complex. This trend toward specialization is driving up the value of technical knowledge, making it more prized than writing skills. To handle the complexity, technical writers may find that they are playing increasingly collaborative roles with engineers to create the needed documentation. To drive up their value in organizations, technical writers should look for ways to collaborate more skillfully with engineers in creating content. Takeaways: The growing complexity in the technology landscape is ratcheting up the importance of technical knowledge in organizations, overshadowing writing skills. Creating documentation is becoming more of a collaborative effort with engineers due to the increasing level of complexity and specialization in the technology landscape. Documentation processes are moving towards docs-as-code tools in part because engineers are more involved in the authoring processes, and they prefer to use tools they’re familiar with. Venue Details about the event from STC Puget sound are here. Date: May 21, 2019 Time: 6:00 pm - 8:30 pm Venue: University of Washington – The Tower 4333 Brooklyn Ave NE Seattle, WA 98195 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 discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i

I recently gave a presentation on technical communication trends to the STC Puget Sound Chapter in Seattle, Washington, on May 21, 2019. This is one of the better presentations on trends I've given and culminates a lot of research and other iterations on this topic during the past year. You can view a recording of the presentation, check out the slides, grab the audio file, and see other details here.

I mentioned in my STC Summit slide links post that I recorded my “Intro to API documentation” presentation using the on-board mic on my laptop, and that STC let me post it on my blog. The sound in the recording isn’t great, but if you’re interested, the video is available below. Someone who recently watched the video wrote me to say, Btw, the one hour crash course was great. I just watched it. This will be my go-to-link to send people interested in the space. It’s a lot of content for a beginner, but its variety and your talking more holistically about the workflow/mindset made it a great introduction. Bravo! In this introductory presentation, I explore Sendgrid as a good example of API docs. For more API documentation recordings, see Video recordings of API doc workshops. I also rendered this video as a standalone audio file in case you prefer it this way: Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. 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 discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i

If you want a condensed, one-hour version of what I cover in my API documentation workshop, check out this crash-course video.

A couple of weeks ago, I gave a full-day API documentation workshop in Raleigh. I recorded the workshop and have made the video and audio content available in my API documentation course here: Video recordings of API doc workshops. There are more than 6 hours of video available for you...

Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Going to an academic conference Last year I started a project aimed at bridging the gap between practitioners and academics, and after a number of conversations with one academic, I was invited to speak at the Symposium for Communicating Complex Information, which is a small conference (held in Louisiana this year) that consists almost entirely of academics. I’m always intrigued at opportunities to attend conferences I’ve never been to before, especially to interact with people I’m not accustomed to interacting with, so I thought a two-day immersion with academics might be fun. I agreed to present on trends in technical communication. The conference took place in Louisiana Tech University’s Academic Success Center in Bossier City (just outside of Shreveport), LA. Presenters followed a format where they spoke for just 15 minutes and then transitioned to 15-minute Q&A with the audience. The presentations demonstrated the breadth of the tech comm discipline, and covered topics as varied as establishing credibility on Facebook to Burkesian dynamics in collaborative writing to wayfinding in hospital emergency departments and more. There wasn’t much time to socialize during the conference, but as the day ended and dinner plans were made, a large group ventured over to a nearby Mexican restaurant where, I soon learned, as is the case at most dinner events at conferences, when the right people get together offline, the real conversations would begin. During a lengthy dinner that lasted two-plus hours, I sat next to academics from various institutions and in different phases of their career — some tenured, others associate, others adjunct, others just embarking on their own PhD journey. Overall, I found a greater understanding of academics that I hadn’t grasped previously. If I can paint a few broad strokes here, it might help more practitioners get a better understanding of the tech comm academic — their challenges, unique situations, and the difficult spaces they inhabit. Some descriptions won’t apply to every academic, for sure, but I hope to capture a common story (at least from my vantage point and the academics I’ve interacted with). The corporate exodus narrative Most striking is that most academics I spoke with started out working in the corporate space, but they had a negative experience that prompted them to reroute their career toward academia. One academic said he used to get regular migraines (caused by stress) while working at a company — migraines so frequent and unexplainable that he sought medical advice. When he switched into academia, these migraines just seemed to vanish. I think his story is symbolic of the common emotional healing that seems to occur when others make the transition into academia. Another told me about how he found the corporate environment too cut-throat, and when I pressed him for details, he explained that his job function was to replace a support group through a knowledge base, and that he was the key instrument in the corporation’s downsizing initiatives. He described how he facilitated local workers sharing desks with their overseas replacements; the local team trained the replacement team for a full week. The many employees let go even included his high school friend. Another explained that while working in his company, every time he suggested that they do user analysis or investigation about their products or docs, the company resisted and dismissed the idea, explaining that they didn’t want to find out that they were wrong; they didn’t want to learn that users might not want the product they were designing. This baffled him. He couldn’t understand why the company wouldn’t want to learn this information. It turned him off to the corporate world. Although everyone has a unique story, I couldn’t help but draw a conclusion that most academics have similar bad experiences in corporations. Thes

Corporations often expect tech comm academics to fashion their curriculums to suit corporate needs; in contrast, academic departments want to give students a safe space free of corporate agendas for critical inquiry. Tech comm academics are often caught between these two groups and must satisfy both.