I'd Rather Be Writing Podcast Feed

Informações:

Sinopsis

A technical writing podcast about the latest trends and practices in the field of technical communication. Technical communication includes topics like technical writing (software help), information architecture, usability, API documentation, information design, web design, illustration, DITA, structured authoring, visual communication, and more. If youre a technical writer or interested in technical writing, this is the one of few podcasts in this niche. I also have a blog at http://idratherbewriting.com where the podcasts and other blog topics are published.

Episodios

  • How to become a voracious reader

    01/12/2017 Duración: 06min

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

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

    28/11/2017 Duración: 14min

    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.

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

    19/11/2017 Duración: 01h05min

    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.

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

    05/10/2017 Duración: 16min

    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.

  • Has plain language deepened or ruined our delight in language?

    20/09/2017 Duración: 18min

    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.

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

    23/08/2017 Duración: 23min

    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.

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

    05/08/2017 Duración: 12min

    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.

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

    04/08/2017 Duración: 35min

    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.

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

    04/08/2017 Duración: 31min

    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.

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

    27/07/2017 Duración: 30min

    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.

  • When the pain of ignorance exceeds the pain of learning

    23/07/2017 Duración: 17min

    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.

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

    13/07/2017 Duración: 18min

    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).

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

    08/06/2017 Duración: 21min

    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.

  • Recording of User-Centered Design Principles for Organizing Documentation

    18/02/2017 Duración: 57min

    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.

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

    24/01/2017 Duración: 01h02min

    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.

  • Recording: Writing tech docs like a hacker with Jekyll

    18/01/2017 Duración: 59min

    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.

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

    15/11/2016 Duración: 01h36min

    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 Open Authoring -- Collaboration Across Disciplines. 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.

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

    18/10/2016 Duración: 55min

    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.

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

    20/09/2016 Duración: 01h05min

    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.

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

    02/09/2016 Duración: 11min

    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.

página 4 de 16