mitmproxy is my preferred proxy for API testing these days. I'm using it mostly in reverse mode though, so I thought I'd capture my setup in case it's useful for anyone else. My main use case is to inspect the traffic coming into the API server and being returned, mostly when running tests against it. Where mitmproxy is typically used as a proxy to monitor traffic passing into/out of a client…
I have a things-as-code project that outputs mostly text-based formats, but a lot of them. To keep an eye on consistency, I rebuild all the outputs and dump them into a local git repository so I can very easily diff to spot any changes - which was fine until we added a build timestamp, so every file looks changed on every run! This post is about ignoring the matching line with git diff -I .
I consider myself pretty git-confident, I've worked with it a lot, taught it, been a git consultant, run engineering and various things-as-code teams. This week I had a spectactular git problem where merging one branch into another produced changes that didn't exist on either branch. Turns out, renaming directories in a monorepo with multiple almost-identical boilerplate documentation files comes…
I use a lot of asciidoc these days for work documentation (and I love it) and I've been so happy that GitHub renders it when you view a repository in the web browser, just like it does for Markdown and ReStructuredText. BUT what GitHub does not do is render the image types that asciidoc does so even though I'm working with asciidoc and PlantUML, and the asciidoc tools render those diagrams nicely…
OpenAPI tags have always been annoying: user-supplied arbitrary data for endpoints should be a fabulous feature - but the documentation tools seem to think that tags are only for them so it becomes more difficult to use tags for other purposes. In fact it is very useful to be able to tag endpoints with lots of different categories of data and so in OpenAPI 3.2, tags were enhanced to include an…
OpenAPI has always had support for simple tags, but the OpenAPI 3.2 release brought in some serious tag upgrades including a summary field, a "kind" field with registry, - and the ability to nest tags which is the focus of today's post. If one level of organisation isn't enough for your API (and on bigger APIs I'd argue it shouldn't be) then the ability to indicate which tag is the parent of this…
Like many of you, my days are dominated by notifications. Emails from project management systems, source control systems, calendar invitations, ticket updates, and message about messages on other platforms. I've noticed that some people use notifications as a power tool, while others seem blind to what happens when they do something. So this post is some tips that I've picked up along the way.
Today I'm sharing a quick-and-dirty script to take an OpenAPI description, spin up a docs server locally, and copy the URL into your clipboard. I also use a bit of glob expansion in my script to find the right folder, because I have a lot of APIs with long and formulaic directory names ( TM Forum members know this story). I'm spinning up Scalar here as it's my current favourite just-works local…
The more I work on API standards, the more I realise how few teams understand that they can adopt the standards and, without breaking any contract, adapt them to make a strong interface for their own application. One of my favourite examples is to add enums where a standard interface cannot dictate the exact values, but in your own implementation it is very helpful to do so.
In my time I've spent a LOT of time on screenshare, and I'm confident sharing my screen. Part of the confidence comes from maintaining a usage pattern that means I CAN confidently share my screen and rarely embarrass myself. After sharing some tips with a former colleague recently, I have tried to package up the best bits of that conversation and turn it into some tips to share.
I'm a big fan of docs-as-code for more or less any type of content publishing, but I'm less of a fan of Jekyll, the default tool used in GitHub pages. I also prefer ReStructuredText over Markdown as a markup format, so Sphinx is definitely on my shortlist of SSGs (Static Site Generators) for my projects. I recently switched the rst2pdf docs to using Sphinx hosted on GitHub pages, so here are my…
Too many open source projects suffer from inadequate documentation, and that hurts their adoption, their communities, and puts more burden on maintainers. Many people who create open source software don't see see themselves as writers, but today I'm sharing tips for documenting open source projects without it needing to take up a huge amount of time to get something published and ready for (docs)…
If you publish a RESTful API and there are situations when you need less (or more!) detail in the API responses from your API - then this post is for you. When I run into this with the teams I advise, the initial problem statement usually arrives more like "We need to move to GraphQL", but this is a solution, not a problem to solve. The problem usually turns out to be either or both of: the API…
API reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical …
I've been using Optic's CLI , an OpenAPI tool that does a bunch of things including diffing OpenAPI descriptions and comparing HTTP traffic with OpenAPI. My use case was an established API that didn't have an OpenAPI file yet - using Optic we could create one as a starting point, and then move to a design-first workflow to make the changes that I was there to help with. For this blog post, I've…
The API DevTools space is alive and well with lots of new and exciting products popping up all the time. I've been especially impressed by the new tools in the docs space , but some of the options are less practical for use as quick human-friendly OpenAPI renderings or previews to use during API development. My current favourite in this space is Scalar because I can get an HTML file to easily…
My slide deck tool ( rst2pdf ) produces PDFs, and I use pdfpc to present the PDF slides. It shows the current and next slides, my notes, a timer, and it probably does other things too that I don't use! I've used it for years but it was really designed for "in real world" presenting with one or two screens. Recently I discovered it also supports some great options for remote presentations, but I…
In a recent project around open source contributors, I wanted to take a look at which projects a particular user (actually a few of them, but I wrote a wrapper to repeat the process for each handle) maintains. GitHub doesn't show this maintainer relationship, so instead I used the v4 GraphQL API and looked at pull request comments on repositories that the user has access to. I'm sharing my query…
For teams that generate OpenAPI from their codebase, there's a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file - and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an…
I come across a lot of "greedy" GitHub Actions, where automation is running across a whole project instead of only on the parts that are relevant. Examples might be code linters that report problems with documentation folders, or the inverse of that. It's especially problematic in monorepos where we probably want to use the same tool when we're doing the same task for different subfolders, but…
Most APIs aren't perfect. By design they are long-lived and may serve many audiences. I see a lot of organisations maintaining multiple versions of APIs, or simply not documenting some of the endpoints to avoid them being included in the published documentation and confusing users. The problem of API redaction is a real one in most organisations, and it goes unsolved or is solved in a way that…
I created an action that needed a rich Markdown value in it, because it's our weekly meeting agenda template which is formatted for humans with links and paragraphs and things. The Action syntax produced errors when trying to add the content directly to the action, but I got it to work by putting the content into the file, and using the file contents as an environment variable. That's really the…
Writing for technical audiences often means sharing code in one form or another. If the code is only for illustration purposes, then it can be included in the article for observation. But if the code is useful or reusable by your readers, then you need a way to make it available to them. I've seen a few questions on this recently (shout out to the DevRel Collective slack for a brilliant discussion…
Wrangling some document conversion the other day, I ended up in a situation where I had the JSON I needed, but in a completely unreadable format. Luckily, this problem is very easily fixable .... when you know how. So today's post is a quick recap on how I did that using jq , a very handy command-line tool for working with JSON. For the impatient, here's the command:
I work or have worked with APIs of all sorts of standards, sometimes many standards at once - or none. Each standard exists for a purpose and might be a great fit, or a terrible fit for other purposes. Today's post is a recap of some of the common API standards around and what you need to know about each one.
API governance needs good tooling, and rules that fit - so today's post covers both. Fun fact: I work at Redocly and had used the tool for years, but recently realised that I have a post about a different tool in the archives of my blog, but no Redocly post. So here's the Lorna-recommended version of OpenAPI linting with Redocly CLI.
Working on API tools, I get to see inside lots of different organisations' API projects and processes. Every scenario is different, but a common theme is that many companies use a more complicated API description workflow than you see in conference slide decks! This article shares my typical workflow, steps and chosen tools that might show up in an API description pipeline.
Creating content requires accuracy as well as creativity and the ability to deliver. Working with docs-as-code gives a strong foundation and structure to work within, and means there's a clear workflow where automation can be added to help us with the easy stuff, such as "do all these links work?". I really appreciate having the extra confidence and support of these types of tools, and having…
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…
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…
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…
With OpenAI's new Actions feature allowing you to get a GPT that uses your own API, many new doors are open. However giving an AI an access token the keys to your API and telling it to have fun may lead you to realise that one of the doors available leads to the empty lift shaft of overwritten data, or the bottomless well of cloud bill shock. To reduce the risks, OpenAI supports an extension…
I've heard a variety of bad advice (and some untruths!) regarding how to version your OpenAPI description lately. Rather than dig into those, instead I'll share my opinion on how I like to version API descriptions in my own projects. Every API project is different, but perhaps there's something here that can help your project too.
I talk to a lot of people about their API lifecycles and processes, and one thing that has value in almost every case is immediate documentation preview for all updates to an OpenAPI description. The time it takes to set it up (about ten minutes now I know what to do) is an investment that makes every future change easier to propose, review, and accept. Here's my recipe for open source OpenAPI…
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…
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…
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…
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…
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…
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…
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?…
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 …
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…
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…
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 …
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…
Whether you are building your own presence, or representing a brand or employer online, it's useful to know what people are saying! Keeping up with all those possible places you should look for news or mentions can be pretty laborious and when things are busy, it's difficult to keep up with this work unless you have some decent tooling in place. There are some great automation offerings around but…
This collection of resources accompanies my keynote talk "Open source is good for business", since it's easier to access links on a web page than in a slide deck. The talk, and these resources, are divided into sections. View Open source is good for business on Notist. About Open Source …
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.
What happened to my blog? Nothing happened, I still blog ... except then I looked at my site the other day and realised, it's been a while.