Podcast: API Design and Usability with Arnaud Lauret (API Handyman)
Arnaud Lauret, also known as the API Handyman, recently published a book called The Design of Web APIs. 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.
When reference docs lack a tutorial -- a look at Wescheme's Bootstrap documentation for students learning programming
This past week my 7th-grade daughter started a programming component in her Algebra class. I was elated about this because, sadly, whenever she needs help with math, I'm usually not much help. My wife is much sharper with math and seems to remember everything, so she takes the lead. But with the switch into programming, I got called up from the dugout to help out. After I browsed the material assigned and required tasks, I started to feel sorry for my daughter, the teacher, and the whole school's attempt to jump into programming.
Upcoming API Documentation Workshop in Los Angeles, Calif., on January 23, 2020
I'm giving an API Documentation Workshop in Los Angeles, California, on January 23, 2020. Details are below. You can register on Eventbrite here.
Reflecting on my latest SF API doc workshop
Last week I gave another API documentation workshop in downtown San Francisco. This was the second API doc workshop that I fully organized from start to finish myself, and overall it went pretty well. In this post, I want to reflect on a few of the things I learned.
Follow-up to 4 Technical Writing Tests Post
It's been a while since I've written a post that has received so many negative comments as 4 Technical Writing Tests to Screen Candidates. Although many people did like the tests and found them interesting or fun, quite a few people had more negative reactions. As a result, I'm scrapping the idea of multiple choice tests as a way to filter candidates.
4 Technical Writing Tests to Screen Candidates
In an attempt to more easily filter technical writing candidates in the hiring process, I'm experimenting with a series of multiple-choice tests to "take the pulse" of any technical writing candidate to easily see whether a candidate is worth moving up to the next level in a hiring process (for example, moving from the resume pile to a phone screen).
WTD Episode 25: Researching how developers use API docs, with Andrew Head
In episode 25, we talk with Andrew Head, Ph.D. Candidate in Computer Science at UC Berkeley, about his research on how developers use API documentation. Specifically, we focused on a recent article he co-authored titled When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects. During the podcast, we chat about the following: where developers look for information, how developers manage information in Google’s unique billion-line code base, when it's appropriate to just let developers read the code directly versus creating documentation, what kind of information developers look for in API documentation, the relevance of document generators such as Doxygen, and more. Andrew also talked about some projects he's working on to build interactive tools for developers to share code expertise.
Long-term strategies for project productivity
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.
Matching documentation review practices to company culture
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.
Some specifications docs I've been working on -- and thoughts on strategies and techniques for managing specs
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.
Podcast with Jacob Moses on the Not-Boring Tech Writer: Skill #26: Getting Started with API Documentation
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.
Podcast: Dealing with Project Overload -- Strategies to Manage Overflowing Documentation Tasks
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.
Podcast: 10 myths about API documentation
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.
Expanding embedded Swagger UI instances in your docs
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.
WTD Episode 24: Conference chatter and the Australian scene, with Swapnil Ogaler
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.
subscribe via RSS