Beholding Stripe’s excellent documentation and wondering how they’ve built it is a modern technical writing trope. It’s no wonder, then, that when Stripe announced that they open sourced their documentation format and framework, Markdoc, folks would get psyched. I, too, was startled by the sudden release. After some initial doubts, I came to love their approach.

A few months ago, I drafted a technical writing syllabus. It features all the topics that a senior technical writer should master at some point when working on software documentation.

Episode 3 of the Let’s Talk Docs podcast is out, hosted by Portia Burton and Eric Holscher (founder of Read the Docs and Write the Docs). Enjoy!

It’s my ritual: every time I enter a secondhand bookshop, I go straight to the Sciences section and search for old computer manuals. They’re very hard to come by, as their owners tend to throw them away once they stop using a particular device or piece of software. Manuals also happen not to be the most engaging read for most people, which adds to their rarity; few want to peruse an old IBM AS/400 handbook while laying at the beach.

Almost two years passed since I published my tips for working remotely. Now that remote work has become almost standard in the software industry, I felt like revisiting that list to add a few items. Enjoy!

Despite the massive growth of docs-as-code as a documentation ethos, I continue to be surprised, year after year, by the lack of robust docs-as-code tools. Most days it feels as if docs-as-code was a giant standing on feet of clay, on the fragile toolchains that we use to create our documentation in all kinds of software companies, from startups to unicorns.

A colleague asked me the other day what’s my favourite way of extracting information from subject-matter experts (SMEs). This is a big topic in technical writing, as most of our time at work is spent chasing engineers and project managers to get bits of information.

My answer was “Be like Lieutenant Columbo”.

The programmatic equivalent of UX Writing is API Design. The words that you use to describe your API enable conversations between software and people - it’s just a bit more structured and mechanical. That’s why technical writers are uniquely suited to assist technical teams in doing API design, especially when an API First design approach is being followed.

I get it. It’s hard to read articles about OpenAI’s coding and writing skills without feeling a shiver of neo-luddite panic running down your spine. Especially when one reads passages like the following.

A hands-on review of the most recent open source API documentation toolchains, such as ReDoc, Widdershins, and Elements, the newest solutions from Stoplight, among others. Get the slides here.