I'd Rather Be Writing

Webinar recording: How Trends in API Documentation Differ from other Tech Comm Trends

Thu, 12 Mar 2020 07:00:00 GMT

I recently gave a webinar on trends in developer docs to the STC Washington DC chapter on March 12, 2020. In this presentation, I presented the results and analysis of my . A recording and audio file is available below.

Hosted on Acast. See acast.com/privacy for more information.

Introduction to API documentation - Recording from Los Angeles API documentation workshop

Wed, 11 Mar 2020 07:00:00 GMT

In January I gave an , and I recorded the first section of the workshop. This section provides an introduction to APIs, including an overview of APIs, the API doc market, info about API popularity, how to submit requests through Postman, and other trends. The recording is available as both a video/audio or standalone audio.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: How Paligo is filling a niche in the CCMS market for complex documentation, with Anders Svensson

Mon, 09 Mar 2020 07:00:00 GMT

I recently chatted with Anders Svensson about how Paligo, a cloud-based CCMS, is filling a niche in the CCMS market for complex documentation needs. Complex documentation refers to documentation with multiple product variants, versions, languages, audiences, and more. In these scenarios, content re-use and scalability become more challenging. Paligo is filling a need for documentation teams that have grown beyond their help authoring tools and need the more robust support that a component content management system (CCMS) offers but without the price tag and implementation timeline.

Hosted on Acast. See acast.com/privacy for more information.

Podcast with Andrew Davis: Hiring API doc writers -- an inside look at fixing broken processes

Sun, 23 Feb 2020 08:00:00 GMT

I recently chatted with , a recruiter for API documentation positions in the San Francisco Bay area, about why it's so difficult to hire technical writers for developer documentation roles. Andrew has more experience and knowledge with developer doc jobs, companies, and recruiting processes than nearly anyone else in the tech comm industry. He actually helped me find my first dev doc job when I transitioned to California years ago. Andrew's company is called . In this interview, Andrew provides an inside look at fixing broken processes around hiring.

Hosted on Acast. See acast.com/privacy for more information.

From API docs to developer portals

Sun, 09 Feb 2020 08:00:00 GMT

One comment I often hear from API workshop participants and other readers is that they want a more advanced API course. I've been thinking about what that more advanced course would involve, in addition to what might be involved in leveling up at my work, and I've come to a realization that I need to transition more from to . Developer portal strategies includes API documentation but also encompasses broader concerns as well, not too different from content strategy.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: API Design and Usability with Arnaud Lauret (API Handyman)

Sat, 07 Dec 2019 08:00:00 GMT

Arnaud Lauret, also known as the API Handyman, recently published a book called . In this podcast, I chat with Arnaud about his book, specifically exploring best practices for designing web APIs and focusing on the roles technical writers can play.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: Dealing with Project Overload -- Strategies to Manage Overflowing Documentation Tasks

Wed, 02 Oct 2019 07:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: 10 myths about API documentation

Sun, 29 Sep 2019 07:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Recording of Tech Comm Trends Presentation (STC Puget Sound chapter)

Sat, 08 Jun 2019 07:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Crash course in API documentation -- a one-hour video

Thu, 16 May 2019 07:00:00 GMT

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

Hosted on Acast. See acast.com/privacy for more information.

Corporate exodus narratives: A close look at the tension between the corporation and academia

Fri, 01 Mar 2019 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Recording and slides for my trends presentation at the Symposium for Communicating Complex Information (SCCI)

Sun, 24 Feb 2019 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

How to become a 10X technical writer in the workplace

Thu, 07 Feb 2019 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

How to motivate users to provide feedback: Show that you're listening to their input

Fri, 01 Feb 2019 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Site analytics from Jan 1 to Dec 31, 2018 -- are more engineers writing docs now?

Mon, 14 Jan 2019 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Recording for Menlo Park API documentation workshop now available -- and some thoughts on using cardioid versus omnidirectional microphones for recording

Tue, 04 Dec 2018 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

New post in Simplifying Complexity series -- Principle 11: Be both a generalist and specialist through your technical acuity

Fri, 30 Nov 2018 08:00:00 GMT

In my , I added a new post called, I also recorded this essay as a narrated podcast.

Hosted on Acast. See acast.com/privacy for more information.

How to avoid being a secretary for engineers

Mon, 19 Nov 2018 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

I'd Rather Be Writing is now an Alexa Flash Briefing skill

Mon, 05 Nov 2018 08:00:00 GMT

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.

Hosted on Acast. See acast.com/privacy for more information.

Upcoming full-day API documentation workshop in Menlo Park

Wed, 31 Oct 2018 07:00:00 GMT

I'm giving a full-day API documentation workshop on Nov 8, 2018, in Menlo Park, California, in coordination with Scott Abel (aka, The Content Wrangler). There are still a few open spots left in the workshop.

Hosted on Acast. See acast.com/privacy for more information.

Preferring technical acuity over specialized knowledge

Wed, 24 Oct 2018 07:00:00 GMT

In the debate between being a specialist or generalist, there's also a third option: developing . A person with a high degree of technical acuity has the technical mindset needed to understand and solve problems across a variety of technical domains. Given the ever growing number of technologies, developing technical acuity can be more advantageous, especially in technical writing contexts since technical writers work with a lot of different technologies.

Hosted on Acast. See acast.com/privacy for more information.

If writing is no longer a marketable skill, what is?

Thu, 09 Aug 2018 07:00:00 GMT

When we try to sell our tech comm skills, promoting our skills doesn't seem to impress people anymore, as writing is considered more of a presumed skill everyone has. To give a sense of value, we need to hyphenate our job titles, becoming more of a hybrid professional.

Hosted on Acast. See acast.com/privacy for more information.

My conflicted thoughts about the decentralized web (while taking the Census of Technical Communicators survey)

Mon, 06 Aug 2018 07:00:00 GMT

Seeing my name in the Census of Technical Communicators survey as a possible source for professional development made me think about the impact of blogs as a learning resource. Advertising encourages bloggers to create rapid-fire, lightweight content in order to increase page views and other attention on the advertised product or service. The proliferation of blog content turns the wheels of social media, creating micro-bursts of attention for companies. The negative impact, however, is that more traditional forms of learning, such as scholarly journal articles and books, take a hit. The web's architecture and monetization model around content is optimized for blog content, so unless other mediums can find a way to become more visible and engaging within the architecture of the web, they will continue their slide into invisibility (at least to mainstream users).

Hosted on Acast. See acast.com/privacy for more information.

Articulating stories that influence product adoption (new article in Simplifying Complexity series)

Tue, 31 Jul 2018 07:00:00 GMT

I added a new article in my ongoing series about simplifying complexity. The article is called and explores why adoption of our products among users doesn't often live up to our expectations. I argue that we need to articulate the story we're telling about the product as well as the story users tell, and identify whether the two are in alignment. Note that you can both read and listen to this article, since I created an audio recording for it.

Hosted on Acast. See acast.com/privacy for more information.

The relationship between academics and practitioners -- Podcast with Kirk St. Amant

Wed, 11 Jul 2018 07:00:00 GMT

In this podcast, I chat with Professor about the relationship between practitioners and academics. Kirk recently co-authored an article about research as a unifying focus to bring academics and practitioners together. Using this article as the basis for discussion, we dive into origins of the divide, why both practitioners and academics of the same field need each other, potential solutions, and more.

Hosted on Acast. See acast.com/privacy for more information.

Reducing the complexity of technical language (new article in Simplifying Complexity series)

Wed, 11 Jul 2018 07:00:00 GMT

I added a new article in my ongoing series about simplifying complexity. The article is called and explores reasons why the language in technical documentation tends become so full of jargon and other unfamiliar terms, and a few solutions for simplifying the language. I emphasize the need to read the competitor's documentation and other articles in the industry to get a sense of the right terms and contexts that users likely expect. I also decided to read the article for those who prefer podcasts.

Hosted on Acast. See acast.com/privacy for more information.

Evaluating the user experience of documentation -- Podcast with Bob Watson

Mon, 18 Jun 2018 07:00:00 GMT

This week I chatted with , an assistant professor of tech comm at , about how to evaluate the user experience of documentation. The idea of doing a podcast came up during a comment thread on a previous post about We had a long exchange in the comment threads and thought it would be good to have a podcast about the topic.

Hosted on Acast. See acast.com/privacy for more information.

Recording of API documentation workshop in Denver

Mon, 12 Mar 2018 07:00:00 GMT

I recently gave a half-day API workshop in Denver on March 10, 2018. Topics in the workshop included how to document reference API content (endpoints, parameters, requests, etc.), what non-reference topics (for example, status and error codes, rate limiting, getting started, sample apps) are common, how to create an OpenAPI specification document and Swagger UI output, and more. You can view a recording of the workshop, browse the slides, and listen to the audio here. Because of the length, the content is divided into three parts.

Hosted on Acast. See acast.com/privacy for more information.

Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation

Thu, 08 Mar 2018 08:00:00 GMT

I recently gave a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018. You can browse the slides and listen to the audio recording here.

Hosted on Acast. See acast.com/privacy for more information.

Recording of OpenAPI and Swagger presentation (for STC and WTD San Diego)

Wed, 14 Feb 2018 08:00:00 GMT

I recently gave a presentation to the STC San Diego chapter and WTD San Diego group called "Swagger UI and the OpenAPI specification" (February 13, 2018). You can view a recording of the presentation, browse the slides, and listen to the audio here.

Hosted on Acast. See acast.com/privacy for more information.

Recording of WTD South Bay presentation: Publishing tools for API documentation

Fri, 19 Jan 2018 08:00:00 GMT

I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. You can view a recording of the presentation, browse the slides, and listen to the audio here.

Hosted on Acast. See acast.com/privacy for more information.

How to become a voracious reader

Fri, 01 Dec 2017 08:00:00 GMT

Voracious reading begins with voracious thinking. Asking questions gives us a purpose and drive for reading.

Hosted on Acast. See acast.com/privacy for more information.

How do you communicate user progress in a course without a Learning Management System (LMS)?

Tue, 28 Nov 2017 08:00:00 GMT

When you don't have a system that logs users in and tracks their progress, it can be a challenge to show their progress in a course. However, rather than showing progress through completed pages, quizzes, or other interactive exercises, progress can also be measured through larger user goals that extend beyond the course. In the case of my API documentation course, the user's goal is to break into the field of API documentation, not so much to finish a course. Breaking into API documentation requires users to build a compelling portfolio, which is how I'm choosing to measure the user's progress.

Hosted on Acast. See acast.com/privacy for more information.

Intro to API Documentation -- recording of presentation to STC Silicon Valley chapter on 11/20/2017

Sun, 19 Nov 2017 08:00:00 GMT

I recently gave a presentation titled "Introduction to API Documentation" to the STC Silicon Valley chapter in Santa Clara, California. The video recording and audio are available here.

Hosted on Acast. See acast.com/privacy for more information.

SwaggerHub: A collaborative platform for working on OpenAPI/Swagger specification files, and more

Thu, 05 Oct 2017 07:00:00 GMT

When documenting REST APIs, the OpenAPI specification (formerly called Swagger) is pretty much the default standard. Yet learning the OpenAPI spec is not a trivial undertaking and requires significant ramp-up. SwaggerHub is a tool can reduce the complexity in creating your OpenAPI spec file because it enables collaboration between both developers and technical writers. This collaboration not only helps compensate for gaps in understanding with the spec, SwaggerHub also offers many other features (such as versioning, content re-use, inline commenting, and more) to make the authoring and publishing experience easier.

Hosted on Acast. See acast.com/privacy for more information.

Has plain language deepened or ruined our delight in language?

Wed, 20 Sep 2017 07:00:00 GMT

Although technical writers champion plain language, embracing plain language for many years can cripple your ability to use more eloquent language, like that of a literary author or essayist. There isn't much room for literary play or playful tones in technical documentation. Following the rules of simple language has distorted my ability to read anything that blatantly violates those rules without questioning the author's word choice and sentence construction. Sometimes I feel that simple language has removed my ability to delight more in language and to express myself in more articulate, interesting ways.

Hosted on Acast. See acast.com/privacy for more information.

Discoveries and realizations while walking down the Docs-as-Code path

Wed, 23 Aug 2017 07:00:00 GMT

This past week I had some good discussions with developers about the right directions in our doc-as-code project at work. I say good discussions, but actually they were challenging. The outcome led me to realize more details about embracing docs as code. The more you treat docs as code, the more you may have to set aside some common tech writer models of handling content and instead embrace the software code workflows entirely. Some of these principles include storing only source code in repositories, building from a build management system, and reducing build pipelines to work with 1 or 2 larger repositories only.

Hosted on Acast. See acast.com/privacy for more information.

Why Stack Overflow's Documentation effort failed -- a few thoughts from a technical writer's perspective

Sat, 05 Aug 2017 07:00:00 GMT

Stack Overflow, mostly known as a forum for answering niche software questions, recently tried to launch a Documentation component to their site. The goal of Documentation was to 'do for Documentation what we did for Q&A'. In other words, provide substantial, valuable information that could be the go-to source for tech docs instead of just one-off answers around niche topics. However, the effort failed and now Stack Overflow is sunsetting their Documentation.

Hosted on Acast. See acast.com/privacy for more information.

Tech docs and Agile: Problems with integrating tech writers into engineering Scrums (Part 1)

Fri, 04 Aug 2017 07:00:00 GMT

Although it seems like documentation should be treated like other features worked on by a Scrum team, frequently it is not. When tech writers try to integrate into engineering Scrum teams, they usually run into a host of challenges. These challenges stem mainly from floating across multiple projects. Often doc tasks aren't assigned points or grouped in with other tasks in a real sprint, nor are tech writers co-located with project teams. This is a two-part post. In this first part, I outline problems for tech writers integrating into Scrum teams. In part 2, I explore solutions.

Hosted on Acast. See acast.com/privacy for more information.

Tech docs and Agile: Alternatives to integrating into engineering Scrums (Part 2)

Fri, 04 Aug 2017 07:00:00 GMT

This is part two in a series on Agile and tech docs. In the previous post, I outlined challenges in integrating into engineering Scrum teams. Some alternatives to Scrum include Kanban, Extreme programming, Waterfall, and various productivity methodologies. The most compelling solution, to me, seems to be to form your own documentation-focused Scrum. This allows you to keep with the same project management approach and language in the company, while also allowing you to avoid the pitfalls previously described with integrating into an engineering Scrum. Even so, there's not an extremely compelling reason for docs to adopt Scrum, so its main aid might be to give you a disciplined approach to your doc work.

Hosted on Acast. See acast.com/privacy for more information.

Why simple language isn't so simple: the struggle to create plain language in documentation

Thu, 27 Jul 2017 07:00:00 GMT

Although you can adjust your content's style to be simpler and more readable, technical documentation introduces many new terms and concepts for readers to learn. Many readers who don't already understand the discourse community may find this language impenetrable. Glossaries and inline tooltips can potentially help novice users, but there's no easy solution for simplifying your language for both novice and expert users.

Hosted on Acast. See acast.com/privacy for more information.

When the pain of ignorance exceeds the pain of learning

Sun, 23 Jul 2017 07:00:00 GMT

Users turn to documentation when the pain of their ignorance exceeds the pain of learning. Unfortunately, this is the worst state of mind to try to learn anything in. To address this impatient state of mind, we need to write documentation in simpler, easier to digest ways. Task-based documentation gets us part way there. But the varying starting points, unique pathway needs, and messy branching complicate the promised simple linear nature of steps. Overall, we need to increase the simplicity factor in our docs much more than we generally do.

Hosted on Acast. See acast.com/privacy for more information.

Transparency in documentation: dealing with limits about what you can and cannot say

Thu, 13 Jul 2017 07:00:00 GMT

Although traditionally as a technical writer you don't run into too many ethical scenarios for docs, sometimes you have situations where your ability to be transparent about a system's limitations gets curtailed by marketing or product management. It can be frustrating to have your documentation filtered like this, but you can take comfort knowing that, given the decentralized nature of information on the web, where any user can post information in forums, blogs, and other sites, the information filtered out of your docs will eventually be published online (it just might not be published by you).

Hosted on Acast. See acast.com/privacy for more information.

Recording of my WTD Portland 2017 presentation on Building navigation for your doc site -- 5 best practices

Thu, 08 Jun 2017 07:00:00 GMT

Here's the recording of the presentation I gave at the Write the Docs 2017 Portland conference. The presentation explores best practices for doc navigation, including principles such as hierarchy, modularity, progressive disclosure, entry point, and wayfinding. The presentation is about 20 minutes long, and you can either watch a video or listen to audio. Other WTD presentation recordings are also available.

Hosted on Acast. See acast.com/privacy for more information.

Recording of User-Centered Design Principles for Organizing Documentation

Sat, 18 Feb 2017 08:00:00 GMT

I recently presented to the STC Twin Cities chapter on User-centered Design Principles for Organizing Documentation. When organizing your documentation, such as arranging navigation titles, workflows, or other wayfinding features, you can apply universal design principles to make your content more user centered. Some of these principles include Modularity, Hierarchy, Five hat racks, and Progressive disclosure. These design principles, based on solid user research from design gurus, will help users better find and navigate your help content. You can view the recording and audio from the event here.

Hosted on Acast. See acast.com/privacy for more information.

Recording: Modern Technical Writing, by Andrew Etter (STC Silicon Valley chapter)

Tue, 24 Jan 2017 08:00:00 GMT

Andrew Etter presented about his book, Modern Technical Writing, to the STC Silicon Valley chapter on January 24, 2017 in Santa Clara, California. In the presentation, Andrew talks about the strategies he implemented at Palantir to change to a new way of doing docs. This new way includes having a smaller team, using text editors, writing in plain text, processing pull requests instead of bugs, and more. He dives into lightweight markup syntax, static site generators, version control tools, and more, as well as challenges he has faced.

Hosted on Acast. See acast.com/privacy for more information.

Recording: Writing tech docs like a hacker with Jekyll

Wed, 18 Jan 2017 08:00:00 GMT

I recently gave a presentation titled Writing tech docs like a hacker with Jekyll to the to the Southern Ontario STC chapter (on Jan 18, 2017). In the presentation, I introduce reasons why we started using Jekyll, how static site generators differ from content management systems, how to get started with Jekyll, and challenges involved in using Jekyll for technical documentation sites.

Hosted on Acast. See acast.com/privacy for more information.

Recording of Open Authoring -- Collaboration Across Disciplines presentation, by Ralph Squillace

Tue, 15 Nov 2016 08:00:00 GMT

Ralph Squillace, a senior content engineer for the Microsoft Azure Infrastructure team based in San Francisco, California, recently gave a presentation to the STC Silicon Valley chapter (on November 14, 2016) on . In the presentation, Ralph talks about Microsoft's approach to scaling their authoring and publishing efforts across the company by embracing Markdown, Github, open source tools, and other processes that allowed everyone in the company to write and contribute to Azure's documentation.

Hosted on Acast. See acast.com/privacy for more information.

Saving Your Sanity Through Better Client Relations -- with Alisa Bonsignore

Tue, 18 Oct 2016 07:00:00 GMT

In this presentation, Alisa Bonsignore, a technical communication consultant based in the San Francisco Bay area, talks about how she developed confidence and experience in consulting with clients about writing projects. In the beginning, Alisa started out by apologizing for projects in which she worked excessive numbers of hours for little pay, often trying to meet last-minute requests that required late nights and zapped her work-family balance. But project by project, she started to understand how to interact with clients in a more professional, self-respecting way. Ultimately this helped save her sanity and build a stable income through a reputable business.

Hosted on Acast. See acast.com/privacy for more information.

How can technical writers thrive in agile environments? Event recording and details

Tue, 20 Sep 2016 07:00:00 GMT

Last Monday we had a record turnout at our STC Silicon Valley chapter (with about 40 attendees). The topic was a panel discussion on how to thrive in agile environments as a technical writer. With 5 panelists all from different companies, the perspectives and practices they shared varied a bit, which showed the adaptations different writers and companies have made with agile to make the process work for them. This post contains a full description and recording of the event.

Hosted on Acast. See acast.com/privacy for more information.

Recording of Let's Tell a Story -- Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)

Fri, 02 Sep 2016 07:00:00 GMT

Matt Ness, a technical writer at Splunk and a co-organizer for WTD San Francisco, recently gave a presentation to the STC Silicon Valley chapter called Let's Tell a Story: Scenario-Based Documentation. In this presentation, Matt talks about ways to integrate storytelling techniques into documentation, drawing upon his experience as a Dungeons and Dragons player and his player experience from other video game or fantasy worlds. To help users on their journeys and quests, you need a narrative to guide them and a manual to help them overcome obstacles. Video, slides, and audio from the presentation are included in this post.

Hosted on Acast. See acast.com/privacy for more information.

Balancing the never-ending list of documentation to write with your natural interests and passions

Fri, 02 Sep 2016 07:00:00 GMT

Sometimes I think that I've covered every possible topic on this blog that is possible to write about, and my muse becomes silent for a while. But then I remember the purpose of the blog -- to be a web-based log, or journal -- and I realize that the only reason I wouldn't have anything to write about is if I stopped having experiences, stopped reflecting on those experiences, and ultimately became a zombie. That zombie state is the death of any career.

Hosted on Acast. See acast.com/privacy for more information.

Presentation recording: Hunting for API developer documentation jobs in the San Francisco Bay area, by Andrew Davis

Mon, 15 Aug 2016 07:00:00 GMT

Andrew Davis recently gave a presentation on finding developer documentation jobs (mostly for API documentation) in the San Francisco Bay area. The title of the presentation is Hunting for Dev Doc Work around the Bay. You can listen to the presentation recording, check out the slides, or just download the audio.

Hosted on Acast. See acast.com/privacy for more information.

The complexities of translation and the need for dynamic variables in the build process

Mon, 15 Aug 2016 07:00:00 GMT

Translation is a complex undertaking that usually requires you to take advantage of dynamic variables and other parameters in your source format in order to generate out different languages. Although most people think of static site generators as containing static content only, it's actually only static output. During the build process, you can take advantage of these more dynamic characteristics to handle rules for outputting to different languages. In this post, I explain some of the details you have to account for (includes, links, images, re-used content, etc.) when managing a translation project using a static site generator such as Jekyll.

Hosted on Acast. See acast.com/privacy for more information.

Will the docs-as-code approach scale? Responding to comments on my Review of Modern Technical Writing

Mon, 01 Aug 2016 07:00:00 GMT

My previous post reviewing Andrew Etter's ebook on Modern Technical Writing got an enormous response. Some readers said the docs-as-code approach works only for small shops and doesn't scale to large projects. They said content re-use and translation also become problematic. However, perhaps the real differentiator shouldn't be product size as much as product category. The docs-as-code approach (which is what I'm calling it) works particularly well for developer documentation, such as API documentation, which usually doesn't contain the same challenges that component content management systems (or CCMSs) were meant to solve.

Hosted on Acast. See acast.com/privacy for more information.

The Story of Paligo: A new browser-based CCMS with all the features you'd ever want

Mon, 01 Aug 2016 07:00:00 GMT

Up until two years ago, Anders Svensson and his colleagues, based in Sweden, provided DITA and XML consulting. They eventually created their own XML-based component content management system (CCMS) called Paligo, which includes a full set of documentation features to handle single-sourcing, translation, and other documentation needs. Paligo solves the challenges that Svensson's customers had been facing for years with other CCMS systems.

Hosted on Acast. See acast.com/privacy for more information.

Review of Andrew Etter's ebook on Modern Technical Writing

Tue, 26 Jul 2016 07:00:00 GMT

In Modern Technical Writing: An Introduction to Software Documentation, which is an e-book you can read on your Kindle, Andrew Etter argues for a model of technical writing that involves lightweight markup languages (like AsciiDoc and Markdown), static site generators (such as Sphinx), distributed version control systems (like Git or Bitbucket), constantly iterating/updating doc content on your website based on analytics, and more. Etter's book resonated with me because it articulates so many of the principles I've felt about how documentation should be.

Hosted on Acast. See acast.com/privacy for more information.

Applying Tim Ferriss' 4-hour work week rules to tech comm projects

Wed, 20 Jul 2016 07:00:00 GMT

Principles in Tim Ferriss' book The 4-Hour Work Week can be applied to tech comm projects. By focusing on the 20% of tasks that result in 80% of the results, limiting your focus to two mission critical tasks a day, empowering those around you to make decisions, and avoiding distractions from trivial tasks, meetings, and email, you can be much more productive in your work. More than crossing off a list of tasks, this approach will likely make your efforts matter.

Hosted on Acast. See acast.com/privacy for more information.

Thoughts on Transforming Documentation Processes presentation at WTD: Evaluating the trend to treat documentation as code

Fri, 15 Jul 2016 07:00:00 GMT

At the last Write the Docs conference, Riona Macnamara, a tech writer working on internal developer documentation at Google, moderated a panel about transforming your documentation process. The panel consisted of four writers from various companies -- Balsamiq, Rackspace, Microsoft, and Twitter. The panelists talked about how they increased collaboration and openness in their company's doc culture by transforming their authoring and publishing processes. Most of these transformations involved adopting a 'docs as code' type approach, which seems to be a growing trend.

Hosted on Acast. See acast.com/privacy for more information.

Context switching and efficiency -- Kanban to the rescue?

Wed, 13 Jul 2016 07:00:00 GMT

In Become More Productive and Motivated, Mattias Sander provides a well-written overview of Lean, which is a strategy for eliminating waste and focusing more on customer value. What interests me most with Sander's discussion about Lean is context-switching and the subsequent strategy of Kanban, which uses cards to regulate flow. While these principles were developed in the context of Japanese car manufacturers (namely Toyota), they apply equally to the technical writer's world.

Hosted on Acast. See acast.com/privacy for more information.

Why Programming Sucks and the fallacy of documentation in the context of code chaos

Tue, 12 Jul 2016 07:00:00 GMT

Yesterday on Write the Docs, someone shared an article titled Programming Sucks, by Peter Welch. More than just a developer monologue, this article seems to hit on universal truths about programming, so much so that the article has been translated into 10 languages and even has a professionally-read audio version on iTunes (which I bought for $2).

Hosted on Acast. See acast.com/privacy for more information.

Thoughts on Documentation Avoidance for Programmers

Sat, 09 Jul 2016 07:00:00 GMT

This past week on the Write the Docs forum, there was a bit of discussion around a recent presentation titled Documentation Avoidance for Programmers. In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing documentation.

Hosted on Acast. See acast.com/privacy for more information.

Presentation recording: Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup, by Ruthie Bendor

Sun, 22 May 2016 07:00:00 GMT

During the May WTD meetup, Ruthie Bendor, a web engineer, gave a presentation titled Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup. This post contains the audio and video recording of her presentation.

Hosted on Acast. See acast.com/privacy for more information.

Recording of Version Control, Writers, and Worfklows by Richard Mateosian

Thu, 17 Dec 2015 08:00:00 GMT

You can watch the recording of Richard Mateosian's November 2015 presentation to the STC Silicon Valley about version control, writers, and workflows.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: Spec-driven Development of REST APIs, with a focus on RAML -- interview with Michael Stowe

Mon, 12 Oct 2015 07:00:00 GMT

Spec-driven development is an approach to developing REST APIs by first describing and prototyping the API through a specification file (such as RAML or Swagger), and then coding the API. The spec not only serves as a contract for the API's development, it can also generate interaction documentation, unit tests, client SDKs, and provide other benefits.

Hosted on Acast. See acast.com/privacy for more information.

Udemy podcast (with me) and infographic on technical writing

Tue, 06 Oct 2015 07:00:00 GMT

Recently I was interviewed by Alex Bankoff from Udemy for a podcast on the field of technical writing. The Udemy team also created an infographic about the topics covered in the podcast.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: The divide between academics and practitioners -- Interview with Lisa Meloncon

Mon, 10 Aug 2015 07:00:00 GMT

In this podcast, I talk with Lisa Meloncon, an associate professor at the University of Cincinnatti, about the academic-practitioner divide.

Hosted on Acast. See acast.com/privacy for more information.

Podcast: How do design, length, and relevance affect how people use API reference docs -- interview with Bob Watson

Thu, 30 Jul 2015 07:00:00 GMT

Bob Watson recently finished a PhD with research that examined how the design and content of API reference docs affects the user's performance. In this podcast, I talk with Bob about his findings and his other research interests, primarily around goal testing to measure documentation's effectiveness.

Hosted on Acast. See acast.com/privacy for more information.

The key to writing good documentation: Testing your instructions

Tue, 07 Jul 2015 07:00:00 GMT

Writing good documentation requires you to set up a test environment and test all of your instructions -- testing the instructions yourself and against a user. Testing instructions can be time consuming and tricky, especially with developer documentation. It's hard to see past personal blind spots and assumptions. But testing instructions gives you access to insight that makes your documentation much more accurate and useful.

Hosted on Acast. See acast.com/privacy for more information.

API Documentation presentation to East Bay STC chapter -- slides and recording

Sat, 16 May 2015 07:00:00 GMT

The other week I gave a introductory presentation on API documentation to the East Bay STC chapter in Silicon Valley. Here are the slides and recording.

Hosted on Acast. See acast.com/privacy for more information.