Email Newsletter

Search results

I'd Rather Be Writing blog

Site update: Switched from Disqus to Commento
I recently switched the commenting service on this blog from Disqus to Commento. Commento is a lightweight commenting service that doesn't insert a bunch of scripts with each page load. It also makes it easier to comment.
What is a DITA Content Management System (CMS)? guest post by John Baker
In this guest post from John Baker, Content Marketing Manager for easyDITA, John explains what a component content management system (CCMS) is and why DITA is often used in these systems. John's article provides a solid introduction to why these larger, more robust systems are used with documentation. The ability to reuse content at a component level, assemble it into documents, track the component's usage across the system, include metadata, automate templates and formatting, and handle other tasks gives you a powerful way to manage content in an enterprise.
Learning about event planning -- life pro tips from Jack Molisani
If you've been following my blog, you know that I've started a series of API documentation workshops that I'm organizing on my own. Yesterday I finished teaching a workshop in Los Angeles, California, to a group of 15 people. Before this workshop, I had the privilege of eating dinner with Jack Molisani, conference organizer extraordinaire for The LavaCon Conference on Content Strategy and TechComm Management, and I got to peer inside the mind of someone who has mastered the art of event planning. In this post, I'll share a few tips that I learned from Jack.
Updated Intro to API documentation topic
I updated the Introduction to API documentation topic in my API doc course in a couple of significant ways. First, I expanded on the many different types of APIs out there (beyond REST). The list now native library APIs, SOAP APIs, RPC-based APIs, gRPC APIs, REST APIs, Voice Assistant APIs, and IoT APIs. I also incorporated research from Smartbear's impressive report called The State of API 2019, which is well worth a read on its own.
Reflections on my 2019 site analytics
Each year I dive into my Google Analytics numbers and try to identify trends on my blog. In 2019, had 1,974,524 page views, or about 5,409 page views a day (225 page views an hour). Traffic to the API doc site increased from 59% to 72%. Overall, this traffic suggests that maintaining a living documentation site that is continually updated might be more valuable than a continual stream of blog posts. I also reflect on my site's gender analytics, which has a slight trend towards more male readers.
Write the Docs Podcast episode 26: Technical writing and Reddit, with Alan Bowman
In episode 26 of the Write the Docs podcast, we talk with Alan Bowman about the technical writing forum on Reddit as well as the WTD Slack channel, comparing and contrasting the two spaces. Topics covered include pros and cons of anonymity on the internet, transparency around sensitive or taboo topics (e.g., salary, masters programs, feelings of overwhelm), age/experience demographics for both communities, balancing honesty with professionalism, responding to posts from overwhelmed tech writers, dealing with recurring topics, strategies for participating, and more.
2020 Developer documentation survey
Around this time of year, I tend to look at tech comm trends for the previous and upcoming year. As I surveyed other tech comm posts about trends, two recent research efforts articles stand out as informative and research-based. Both of these articles were published in the December 2018 issue of Intercom: Saul Carliner's Tech Comm Census results, and Scott Abel's Benchmarking Survey results. Although informative, I wanted to see data more specific to developer documentation, a specialized niche within tech comm, so I decided to create my own survey.
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).
Write the Docs Podcast 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.