Category Archives: tech

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 →

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 →
31 Mar
2022

Who are you writing that commit message for?

I read a lot of commit messages that make me wonder who the committer had in mind when they wrote it. If you don’t read commit messages yourself, I think that can make it even more difficult to think about who the audience is, or when someone would be reading those entries. Perhaps you’re writing for nobody, or work in a team that doesn’t value the metadata that a single sentence written in the moment can deliver.

Next time you write a commit message, try some of these suggestions as your imaginary audience:

  • Yourself, next week, when you finally get back to working on this thing and can’t remember where you were up to
  • Yourself, when you get a pull request review and can’t remember which commit something is in that needs to be removed
  • Yourself, debugging how this ended up like this, 6 months from now
  • Your colleague, eyeballing your work to see how you are getting on

Personally, I think of it as a note to myself. Like an alibi, if someone asks you what’s already been done, or what this commit that removes one specific line from a long config file. Yes, I worked as a git consultant for a while, the delete-a-single-line with the commit message “Fixed” is always the culprit!

Further reading: https://cbea.ms/git-commit/

16 Feb
2022

Weekly Planning with Obsidian

Keeping on top of tasks at work has been a work in progress throughout my career. However now I’m doing a more managerial role, I also need to keep track of all the meetings and preparation/followup work in my meetings. I find my daily log fills so many pages of notebook that I moved my weekly plan to a separate section – and then to my preferred digital notes tool, Obsidian. If you’re interested in my setup, read on. Continue reading →
05 Jan
2022

VSCode setup for technical writers

I’m working almost entirely with docs-as-code setups for prose at work these days and while I do use vim for most of what I do, VSCode is increasingly in the mix. It’s just about accessible enough with keyboard shortcuts and the command palette for me, and I thought I’d share the extensions I’m using and find helpful. Continue reading →
10 Sep
2021

Sphinx front matter and template variables

I’m building a docs-as-code site at work at the moment (you can peek if you like https://developer.aiven.io) and working with ReStructuredText in this setup is new to me. One thing I really missed was the concept of front matter, which I’m not sure is even official or documented but seems to be reasonably widely supported (I promise to save the rant about markdown for another day). It took me a while to figure this out for Sphinx/rst but now I’m looking at it working, I had better write it down before I forget! Continue reading →
18 Aug
2021

Use Database Connection Strings with Laravel 8

I’ve been doing a lot of database stuff lately, and not much PHP, so when I returned to make my first Laravel project for a while, I had to check the docs to remind myself how some of this works. I noticed that the default approach to database credentials is still to use separate credentials for the host, port, and other variables. I’m using Aiven databases (because I work there and managed databases are great for demo apps as well as real ones!) which supply connection strings, but Laravel supports these too. Continue reading →