In January I gave an API documentation workshop in Los Angeles, and I recorded the first section of the workshop. This section provides an introduction to APIs, including an overview of APIs, the API doc market, info about API popularity, how to submit requests through Postman, and other trends. The recording is available as both a video/audio or standalone audio.
In a recent episode of The Manuscript, a new podcast by Breno Barreto, Breno asked me questions about blogging and motivations and such. I explained two different modes of writing: explanatory writing versus exploratory writing. Technical documentation is explanatory writing, but many of the posts on my blog are exploratory. Breno asked whether there's a place for exploratory writing in the workplace. This is the great question that every humanities-based or otherwise curious person who is immersed in a corporate world must ask in order to thrive.
I recently chatted with Anders Svensson about how Paligo, a cloud-based CCMS, is filling a niche in the CCMS market for complex documentation needs. Complex documentation refers to documentation with multiple product variants, versions, languages, audiences, and more. In these scenarios, content re-use and scalability become more challenging. Paligo is filling a need for documentation teams that have grown beyond their help authoring tools and need the more robust support that a component content management system (CCMS) offers but without the price tag and implementation timeline.
The Manuscript is a new tech comm podcast produced by Breno Barreto, a technical writer working for VTEX in Brazil. Breno interviewed me for episode 2, titled How technical should a tech writer be? In this podcast, we talked about changes in the tech comm field, how I got started, comparisons with copywriting, API docs, processes for tech writing at Amazon, explanatory writing versus exploratory writing, trends I'm seeing, and more.
In your reading for the week, check out The Ideal Documentation Suite for Software Developers, by Paul Gustafson. In this article, Paul answers the question, What does Expert Support recommend for the contents of an ideal documentation suite for software targeted at software developers?
I recently chatted with Andrew Davis, a recruiter for API documentation positions in the San Francisco Bay area, about why it's so difficult to hire technical writers for developer documentation roles. Andrew has more experience and knowledge with developer doc jobs, companies, and recruiting processes than nearly anyone else in the tech comm industry. He actually helped me find my first dev doc job when I transitioned to California years ago. Andrew's company is called Synergistech Communications. In this interview, Andrew provides an inside look at fixing broken processes around hiring.
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.
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.
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.
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.
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?
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.
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.
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.
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.
