WTD Podcast episode 27: Starting a doc group/process when you're the first
In episode 27 of the Write the Docs podcast, we're joined by Cynthia Ng and Amy Qualls from GitLab to talk about strategies for starting up docs in organizations where there aren't any other tech writers and where you're first on scene setting up shop. What are your first steps as a documentarian when there isn't anyone else, when processes, contacts, tools, and other systems aren't documented or described anywhere? When you're first on scene, docs might not even be your full-time job but rather a task that's on the side of your desk and which you have to bootstrap from ground zero.
*How* you write influences *what* you write — interpreting trends through movements from PDF to web, DITA, wikis, CCMSs, and docs-as-code
In tech comm tool usage over the past 50 years, we've seen tools trends ranging from PDF to web, XML, wikis, CCMSs, and docs-as-code. Although some dismiss tools as short-lived and always changing, the tools and technologies we use do influence what we write, to a degree.
New podcast: Unifying Technical Content Sets into a Broader Ecosystem, with Cruce Sanders at [A]
Cruce Sanders at [A] recently interviewed me for his podcast series Towards a Smarter World. The episode is called Unifying Technical Content Sets into a Broader Ecosystem, and we chat about some issues I wrote in an earlier article about agile teams and enterprise content strategy.
Tools FAQ for API doc site
I've started adding responses to API doc questions to a FAQ page in my API doc course. I added three of the latest responses so far to questions. Since I anticipate a lot of questions around tools, I dedicated this page as the Tools FAQ.
Autonomous Agile Teams and Enterprise Content Strategy: An Impossible Combination?
Agile software development seems to favor independent, autonomous teams. In contrast, enterprise content strategy looks to harmonize content across multiple teams and boundaries. In a current software development model where agile dominates as the norm, how do you reconcile larger needs for enterprise content strategy?
From API docs to developer portals
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 API documentation to developer portal strategies. Developer portal strategies includes API documentation but also encompasses broader concerns as well, not too different from content strategy.
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.
Upcoming webinar: How Trends in API Documentation Differ from other Tech Comm Trends
I'm giving a webinar on trends in developer docs on March 12, 2020. The webinar is through the STC Washington DC chapter but anyone is invited to attend. Details are below.
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, idratherbewriting.com 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.
WTD 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.