One strategy for maintaining productivity when working on multiple projects is to try to complete one main task on each project each day. I have an illustration with arrows and blocks that helps keep me on track and aligns my focus in the long-term.
Although I've been doing tech writing for enough years that this issue shouldn't even be an issue, I'm still perplexed by best practices around document review. The right practices seem to vary from company to company, from toolset to toolset, from group to group. I've written previously about various review practices, but in this post, I'll reflect on Amazon's document review process.
Although specification documentation (which covers technical information about product details), doesn't involve much actual writing, it does require you to make many judgments about what information to include, how to gather and retrieve these details, and how to structure and present the information. These tasks are at the heart of technical communication.
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.
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.
One challenge with REST API docs, if you're generating out the reference content using Open API, is how to embed Swagger UI in your docs in a seamless way that doesn't look like a website within a website. In this post, I explain how to embed a Navigation toggle to hide your sidebar and give more width to the embedded Swagger UI display.
In this episode, Chris and Jared are joined by the Write the Docs Australia initiator Swapnil Ogale. They talk about conference wind-downs and ramp-ups, highlights from the just-finished WTD Prague conference, speakers announced for upcoming Write the Docs Australia conference, the "Good Docs Project," the tech writing scene in Australia, and more.
In this episode of the Write the Docs podcast, rather than the usual roundtable discussion, we provide a recording of a WTD Berlin presentation by Lucie Le Naour on how to write inclusive tech documentation. Inclusive documentation takes into account all users, regardless of their gender, culture, or abilities. It uses language that treats different types of people fairly and equally, acknowledging that the words you choose matter in the connotations and attitudes they convey. This presentation was recorded on August 19, 2019 in Berlin.
DeveloperHub is a new publishing platform for API documentation that lets you combine your API reference information with tutorials and other documentation, complete with search, branding, navigation, and other features in a developer portal. In this post, I asked Zaid Daba'een, CEO & Founder of DeveloperHub, to share a bit of info about DeveloperHub.
I'm giving an API Documentation Workshop in San Francisco, California, on November 19, 2019. You can register on Eventbrite here.
This past week I held my first API documentation workshop in which I organized it from start to finish myself (handling registration, venue, dates, catering, marketing, setup, and other details), and now I'd like to reflect a bit on it.
I added a new article in my API doc course that expands the notion of docs as code to include not only tools but processes as well. I included an excerpt below and a link to the full article.
A reader recently asked how to collaborate with Git with other writers. He said they found it hard to develop a Git workflow that allowed them to work on content together and wondered if another approach might be more suitable.
Previous articles I've shared on documenting code introduced the complexity of the challenge. In this article, I expand on five different techniques writers take in documenting their code, including the Lego approach, the Nautilus approach, juxtaposed columns, and more. In particular, I expand on why describing the finalized code might not be so instructive for users, and why it's nearly impossible for writers to decompile the developer's logic that led to the finalized code anyway. See Five strategies for documenting code.
