From The Blog

Selective prose linting with Vale’s glob switch

Vale is an open source CLI tool for linting prose (if you’re not linting prose yet, why not? I never want to go back). I typically use it for everything, locally and in CI, and it’s especially valuable now I’m working for a company that uses US English. You’d think that most of the challenges would be caused by the majority of non-native English language contributors? Nope, most of the chaos comes from the token Brit :)

I ran into one challenge though where I didn’t want to enable Vale for everything: a large internal documentation repo. This is the catch-all of things we should share with one another and like most internal company documentation sites, there is a lot going on. I assembled a very minimal set of Vale rules and still the first pass netted me over 10k errors. Luckily, Vale has a --glob option, but it took me a while to find how to exclude multiple files and directories using it, so here’s the example for future-me, and anyone else who needs to see it! Continue reading

Visualise OpenAPI with Blockly

Giving talks about OpenAPI often means lots and lots of slides of YAML. In fact, one of my talks even contains a “warning, contains yaml” slide! If you aren’t a professional yaml developer, it can be difficult to digest and learn from, and so I wanted to do better. The various elements are nested inside one another, and so I had this idea to build a representation of OpenAPI using Blockly (the tooling also used for Scratch, if you’ve seen that).

Showing tags with descriptions
Continue reading

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

Talks, Articles, Podcasts, and More

Slides

API governance without tears


APIDays, September 2023
Slides

OpenAPI for Documentarians


WriteTheDocs Atlantic, September 2023
Slides

Design-first APIs with OpenAPI


Laravel Live UK, June 2023
Slides

OpenAPI for Documentarians


APItheDocs, June 2023
Slides

API governance without tears


EndpointCon, May 2023