Last night I listened to an episode of the “The Future of Content” podcast 🎧 where Lorna Mitchell was the guest on the show. I don’t usually subscribe to this podcast, but because I know and follow Lorna, I discovered this episode.
It was a delightful 31-minute conversation, which I can recommend. I don’t want to summarize the entire episode, but I wanted to repeat a few significant points.
A lot of the episode dealt with the docs-as-code workflow. With docs-as-code, technical writers use tools like Markdown and Git to manage their content in a similar workflow as developers. That workflow appears to be an overall trend as it brings implementation and documentation closer together.
Additionally, it ties in well with two other aspects. One is reusability. Lorna stressed the importance of keeping the content and presentation separate. While this might seem obvious to developers (think HTML for structure, CSS for style), for documentarians working with WYSIWYG tools like Microsoft Word, it is a new concept. The huge advantage is that you can repurpose content in different ways, for example, between various conference talks, your website, a PDF whitepaper, and more.
The other aspect is, and that is specifically for APIs, the use of OpenAPI. Apart from a short “elevator pitch” from Lorna about how great OpenAPI is, the episode didn’t dive in too deep. But it reminded me of the unconference session I attended at the last virtual API the Docs event. In the course, we talked about how companies are doing exciting things with build pipelines that combine structured documentation (e.g., API references in OpenAPI) with Markdown files for more free-form documentation.
At the end of the episode, there was also a short conversation about Twitch streamers and how they explore new ways of explaining programming and technical concepts.
If you need assistance with your APIs, their documentation, and content production for developers, I think this is a great time to plug my freelance consulting business. You can learn more about my services and contact me through my website.