From The Blog

Reviewdog filter settings with GitHub Actions

Reviewdog is a tool to use with GitHub actions for applying review tools in your CI. I use it with Vale, and it’s really good. One thing that has tripped me up multiple times is that by default, it only applies the checks to the changes in the pull request, not to the whole project. So when you add something like Vale, which is a prose linter, it only checks … the workflow file you just added! I always forget that it works this way, and how to change it, so I’m pasting some examples for future reference. Continue reading

Short tech writing style guide for developers

Style guides are vital to successful publishing projects, but they are usually too extensive for casual contributors. After running a number of projects with developers rather than specialist documentarians as the main contributors, I’ve started using a short-form style guide, short enough to be read and used by people who don’t spend as much time thinking about these things as a full time writer does. The main version is published on GitHub, but I’m also sharing the current version here. Continue reading

API Linting Levels

I’ve been thinking about API linting lately, partly because I work on a tool for API linting in my day job, and partly because I get quite a lot of questions from teams wanting to improve their API quality. The “best” ruleset depends entirely on your context, where you are in your API practice journey, and how much you want to invest in the API in question. I typically use a 4-levels model of API linting readiness, and I’m sharing them so that you can find yourself on the map and see where you might go from here. Continue reading

Talks, Articles, Podcasts, and More

Slides

Developer Experience in Open Source Projects


State of Open Con, February 2024
Slides

Open Source DocOps


FOSDEM, February 2024
Slides

Intro to OpenAPI


FOSDEM, February 2024
Speaker

Redocly and OpenAPI


APIs You Won't Hate, January 2024
Slides

Docs-As-Code, for Coders


TechMids, October 2023
Video

Repeatably Better APIs


Treblle Hacktoberfest, October 2023