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 … Continue reading →| LornaJane
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 … Continue reading →| LornaJane
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 proj| LornaJane
Welcome! I'm Lorna: open source technology leader and developer experience engineer. I'm a striking combination of technical experience, communication skills, and a genuine love for enabling others to succeed. I'm a leader, an engineer, a writer, a user champion, an open source maintainer, and a pub| lornajane.net
Lorna Jane Mitchell's Website| lornajane.net
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| LornaJane
Change the fields returned by your API by offering more representations of the resources. This under-appreciated feature of API design can help teams to get the best from their API for multiple use cases, without the need to switch to GraphQL.| LornaJane
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| LornaJane
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 d| LornaJane
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 deve| LornaJane
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 s| LornaJane
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| LornaJane
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| LornaJane
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| LornaJane
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! Without sharing any one organisation's| LornaJane
Set up link checking on your docs-as-code projects. This post explains the key design decisions you'll need to take, and shows some sample code for implementing with GitHub actions.| LornaJane
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| LornaJane
