Tag Archives: docs

12 Jun
2023

Tips for better documentation with OpenAPI

I love documentation, which is supposed to be rare for software engineers. I am pretty sure that loving documentation is actually very common, but not very cool and so few people admit to it! I love reading good docs, and so I love writing them too. Between hanging out in the Write the Docs community, and recently being at the APItheDocs conference, I’ve answered a bunch of questions about getting good documentation from an OpenAPI document, so I thought I’d round them up in case it’s useful. Continue reading →
08 Nov
2022

Sphinx extensions for developer portals

I’ve been gushing about docs-as-code, but realised that I haven’t shared many hands-on tips for actually building different types of sites in this sort of toolchain. I’ve been mostly using Sphinx which generates much better-looking documentation than its website suggests. It’s a python-based static site generator, with a thriving community and lots of great extensions. Today I thought I’d share the extensions I use the most for developer portals (like the Aiven docs, one of my work projects and the source of the screenshots in this post) and what I like about them. Spoiler: may contain a theme as well as the extensions.
05 Sep
2018

Muffet: quick and easy link checking

In my not-so-new job I work on Nexmo’s developer portal and that means a lot of documents, a lot of links, just a lot to keep track of! One thing I worry about is changing something and breaking links from somewhere else, so I wanted to be able to check for existing links, broken links, and to include internal links like http://example.com/home#something as well since all our titles are linkable in that way.

Enter: muffet Continue reading →