23 Aug
2023

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 →

20 Jun
2023

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 →

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 Mar
2023

Raising the Next Generation of DevRel

Developer Relations isn’t new, but it’s also broad, ill-defined, and constantly evolving. It’s difficult to keep your own skills up to date, never mind coping with a whole team full of people and constantly creeping industry scope. The required combination of specialist and generalist skills to be successful is any of the Developer Relations and allied roles is extensive, and it’s easy to feel overwhelmed and end up coasting being just-good-enough at things but never feeling mastery.

As an individual contributor, manager and general DevRel presence over the years, I’ve developed some tactics both for myself and my team, and I’d like to share them in case they’re useful to others. Also since I’m moving to a less DevRel role, writing this down while I can still think about it! Continue reading →

28 Feb
2023

Improve Existing OpenAPI Descriptions

I’m a firm fan of a design-first approach to building APIs, and advocate for it at every opportunity. Repeatedly. Design-first means that an API change starts in the OpenAPI description, gets reviewed and approved by the stakeholders, and then gets built afterwards.

I also live in the real world, where OpenAPI descriptions get generated from existing codebases, and engineering teams lack either the knowledge or the enthusiasm to modernise their processes. With a generated OpenAPI description, everything else that OpenAPI enables is likely to be disappointing, because the description only contains the information that was in the serverside code, and if you’re lucky some comment metadata. Enter OpenAPI Overlays, a way to describe alterations to an existing OpenAPI description that can be reapplied every time that description changes. Continue reading →

26 Feb
2023

Manager’s Secret Second Calendar

Employees expect a lot from their managers, and as managers we do our best to meet those expectations. However most managers are only human (I’ve met a few that I had doubts about), and so it can be difficult to get absolutely everything right absolutely all the time. I’d like to share a tactic that I learned from another manager around the time that I took my first line manager role, that I think really helped me to at least give the impression that I knew what was going on: a second calendar, visible only to you, with key dates in. Continue reading →
03 Jan
2023

Generating a nice-looking PDF with Pandoc

Pandoc is one of my favourite tools in the world. If you haven’t come across it before, it converts between more or less any two document formats. I use it a lot with MarkDown and ReStructuredText so that I can produce content efficiently and then share it in a way that looks nice, but also to get word documents into cleaner formats. However the PDF output has always looked a little bit … dated? (this is rich from an rst2pdf maintainer I know!) and I was recently delighted to find some tricks that resulted in a better PDF. I’m sharing them here, so I can find them again in the future; you are welcome to use them too, of course! 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.
26 Sep
2022

Internal DevRel: Colleague Enablement

I work in Developer Relations for a very technical company (Aiven), and I usually describe my job as half explaining my employer’s technology to developers, and half explaining developers to my employers. However in the last year or so, I’ve realised that there is a variation on this theme that is impactful for my internal colleagues: explaining technology and developers to people who are experts in something else. I work with specialists in various aspects of sales and marketing (DevRel reports into Marketing) and my colleagues are genuinely curious to know more about the domain we work in! I thought I’d share more about how I enable my colleagues, and why I think it works for us. Continue reading →
11 Apr
2022

Outline your writing to ease the creative process

For most of my career I’ve been a software developer, but now I’m mostly a communicator. As a manager, I give the right level of detail to many different audiences, and I deliver that in words they can understand. As a Developer Advocate, I explain complex technical concepts in useful, memorable, and occasionally entertaining ways. However the best software developers are lazy and I’m still always looking for ways to get things done with less effort on my part! For writing, the best process I know feels like unnecessary overhead, but it’s always worth it in the end so today I’m sharing my secrets: create an outline before you start. Continue reading →