Target a single audience and outcome

Know who you are writing for. The new junior developer needs different context and explanation than the Ops person trying to follow disaster recovery documentation. If it helps to think of a specific individual, do that. The key here is to not write down what you know, but write down what the reader needs to reach the desired outcome. An example outcome could be completing a task, learning about a specific topic, or understanding a set of options.

Structure your writing

If your organisation offers templates, always use them; consistency helps readers a lot, even if the content is created by many authors. If not, try the Diátaxis framework as inspiration on how to frame different content types – and don’t be afraid to create more than one article from a single topic or assignment. If no structure is provided as a template, create your own by writing the subheadings of the piece before you write the words.

Use subheadings, images or diagrams, lists, and other content types to communicate to your readers. This “page furniture” helps them to navigate potentially long and complex technical articles.

Be positive and inclusive

Focus on things the user can do. Don’t explain what can’t be done, isn’t supported, or hasn’t been implmented yet unless these are central to the topic.

Example: Instead of “you cannot back up your data yourself” you could say “data backups can be arranged by contacting the support team”.

Inclusive language helps make your writing useful to the widest possible range of people. Avoid gendered language, using “they” and “theirs” rather than “he” or “she”. Even when this feels clunky to write, it makes a positive impact on your readers. Other language to find alternatives for includes terms that could seem ableist such as using “OCD” or “crazy” in your writing. It’s already standard practice to avoid socially-loaded terminology such as master/slave, blacklist/whitelist, and so on. Keeping a wordlist that is automatically checked, or using a tool like AlexJS can help with spotting words and phrases that can be improved.

Beware of jargon and abbreviations, because they can be difficult for newcomers to understand. Expand your abbreviations the first time you use them, and link to definitions or supporting content for any special terms to give the user the option of reading on , or clicking the link to learn more.

Write commanding titles

Titles should use imperative language to make it clear what the reader is doing in each section. It can feel like an abrupt style, but imagine ordering a small robot to perform each action and you will be pretty close. The side benefits of this approach are that it’s often easier to translate, and tends to match user search terms more closely.

Example: Instead of “Configuring the widget” use “Configure the widget”

Use sentence case for titles, and check them automatically using a tool like Vale. Add product names and other proper nouns to Vale to avoid false reports.

Choose examples and screenshots wisely

If a picture is worth a thousand words, then a good example is worth at least twice that amount. In both cases:

• Choose content that the user will know or easily understand. Avoid “foo”, and instead use “Alice” if it’s a name, “Bucket” if it’s a product, “paleblue” if it’s a colour, and so on. Your reader will internalise that their data should look like your data.
• Avoid pop culture references, using these can exclude groups from other demographics than your own.
• Every example and screenshot needs text with it, explaining what it shows and why that’s useful to the user.

Code examples are always valuable, adding more examples is usually a good thing.

Screenshots are both more difficult to get right and more difficult to maintain over time since small changes to a UI will mean repeating all the screenshots. Use them when you think the user would be likely to struggle with words alone. If you take a series of screenshots, use a small and consistent window size for them all. Always reduce the file size as much as you can, and include alt text on every image (tools such as Markdownlint can check for alt text automatically).

Add hyperlinks

Add links. Link to the tools you mention, the concepts that the user might not know already, and to other articles that are likely to be useful to this reader. Adding links to supporting material can enrich all content types, and help the reader to find their way to success.

Choose words that represent where the link goes to, such as “see the section on hyperlinks“. Some tools will offer the links with their link text as a list, so meaningful words or phrases and avoiding duplicate link text within a page is good practice.

Avoid technical documentation missteps

Technical writing has some unwritten norms that exist for mostly good reasons of readability and comprehension. In particular, here are some things you should NOT do:

• Use exclamation points. It’s not a gossip magazine, it’s technical documentation.
• Use question marks, especially in titles. It very easily reads like a car advert.
• Add emoji, unless the platform you are writing for has it as an established acceptable practice. Emoji are difficult to keep consistent between authors, can be distracting, and can also make the content less accessible.

This post is part of API Futures 2024, a series of posts by different contributors focused on the challenges for this year. My big wish is for everyone to find API tooling and configuration that fits their own context, which is why I’m publishing this linting levels post as part of the event.

Level 0: A valid API description

This sounds basic but a surprising number of public APIs either have no API description, or their OpenAPI description is actually invalid in some way. It may well work with the tools used in the producer organisation, but unless you supply a file that works with all other tools, there are limits to who can use and interact with your API.

Add some unopinionated validation to your CI workflow, and make sure that anyone who works on your API can also run those tools locally while they’re making changes – and you can graduate to the next level immediately :) Redocly has a rule for linting against the specification which is a great starting point (other API linting tools are available!). For the next level, there’s a great ruleset in the Redocly CLI Cookbook that you can copy and paste into your own projects; it aims to catch the things that match the declared data structure of OpenAPI and yet make absolutely no sense in the real world!

Level 1: Meets basic standards

Every API probably should have its own set of basic standards but I typically ask about the API linting rules that are already in place, such as:
– are there checks that security has been declared on every endpoint?
– is there useful metadata, such as a license and some contact information?
– does the API follow a design, such as RESTful API design, and how clear is that from the OpenAPI description?
– are consistent data formats used, such as cents (or equivalent) for money, ISO format dates, standard scientific units for measures?

Having some sort of API design, with some level of data handling, some supporting metadata, and some security practices in place is a level 1 API. Some APIs only need to be at level 1, such as a service with one or two endpoints that handles something non-critical such as newsletter signups. Sure, this API could be brought to a higher API standard and that could be enforced by tools and linting. But not every API needs the same level of investment or must comply with the same standards. Within an organisation, have a few defined levels, and make clear which APIs meet which standards.

Level 2: Has a consistent interface

There are few things more irritating than an inconsistent API, and yet a deeply consistent API interface is essentially an invisible feature. Users will very quickly feel comfortable and be productive using your API platform, but not being irritating is rarely given as customer feedback! So what are the ingredients for this developer happiness level of API standard? You can think of it as having two main elements: the philosophy, and the mechanics.

The mechanics is the simplest thing to get right. It means using plurals (or not), absolutely everywhere. Always using exactly the same variable name to refer to the same data, wherever it is used, and validating that data exactly the same way in both request and response for every endpoint. Having endpoints that are consistent in their shape and depth, and keeping common parameter patterns for features such as filtering or pagination the same everywhere. Adding linting rules to an existing API for this level of API standard can be quite tough, but add the rules you want to follow, with exceptions for any existing/legacy endpoints that aren’t compliant. Enabling the checks on the API, and acknowledging the parts that are known and shouldn’t fail the build, means you can automate the checks and add no more violations! The ignores list can also serve as a to-do list for things to work on, either by making backwards-compatible changes or to revisit if a new API version is in the works.

The philosophy part is a bit more difficult to think about but building on prior art in your APIs, for example by following established RESTful API design practices very tightly and adopting other standards that are already known and accepted. This approach means you don’t have too many decisions to make since you’re following existing and established standards, and the ideas may be familiar/supported by the users/tools that access your API. I particularly recommend looking into Hypertext Application Language (HAL) if you include links in the resources you return from your API endpoints, and RFC 9457: Problem details for APIs (replaces the better-known RFC 7807).

Level 3: Is a joy to use

We don’t describe developer experiences as “joy” often enough, but a really great API description definitely qualifies. If your API is your flagship product, or drives a lot of business value that is realised by strong integrations – this is the level you want to aim at. What’s funny about these top-level APIs is that their actual API design isn’t much different to the earlier levels, however the implementation and supporting materials are the special sauce.

To produce an API at this level, the API governance expands into a more holistic view of the API and what really makes an API experience joyful. This can be achieved with rich OpenAPI descriptions, and supporting documentation as the main pillars. I think there’s also an element here of discoverability, and that this aspect will only become more important in the future.

Enriching OpenAPI descriptions can take many forms. Make the most of the description fields; these support Markdown so don’t be afraid to add links, lists, or whatever else would help the user. From the very top level, where info.description sets the scene and purpose for the whole API, through the individual endpoint descriptions and down to the individual parameter and schema fields, the descriptions are the magic sauce. Explain not just what the thing is, but also what it does, and why the user would want to do that. Enrich also with meaningful and illustrative examples, using (culturally varied) example data that represents something a user really would be doing, rather than “foo” or “bar”. A project name could be “holiday_planning” and an email address “email@example.com”, and using values like this does make a more successful and happier end user.

The documentation is not just the reference documentation either. I haven’t seen linting rules for this, so perhaps it’s a little out of scope, but adding meaningful onboarding documentation or getting started guides, and tutorials for the most common tasks in an API are both excellent additions that make a good API into a great API.

Make your API next-level

Don’t be put off by API standards tooling that comes with big opinions of its own. Reflecting on what your API needs, and what your organisation can support, will help you find which level you are on and where you want to be and set your API projects up for success. Tune the API linting rules to get the support you need, but don’t be afraid to turn things off that aren’t important to you! All the tools come with default rules, but every situation is different so take the time to adjust it for your context rather than gritting your teeth and dealing with someone else’s ideals.

I’m not doing much with OpenAI right now, but I do plenty with OpenAPI and the question “how do I add this field to my existing API description?” is one that I can answer! What’s more, you can use the advice in this post to add other extensions or additions to your OpenAPI descriptions using Overlays, this advice isn’t OpenAI-specific, but it’s used in the examples.

(is anyone else confused by the OpenAI vs OpenAPI similarity yet? I am ….)

OpenAPI Overlays

The OpenAPI Initiative has a group working on a feature called Overlays which solves exactly this problem, where the OpenAPI description exists, but needs some tweaks. Sadly, not very many tools support this yet – the ones I know of are my overlays-js library that I’ll use for the examples in this post, and Speakeasy CLI.

Overlay Example

This example shows an Overlay that adds the x-openai-isConsequential field to all POST endpoints:

overlay: 1.0.0
info:
title: Add OpenAPI annotations
version: 1.0.0
actions:
- target: "$.paths.*.post"
update:
x-openai-isConsequential: true

The target field accepts JSONPath, so edit this expression as required to capture the endpoints you want to flag. Note also that you can add as many action steps as you need to, so if it’s simpler to add specific targets rather than trying to JSONPath to the right subset, that is an option! (there’s a bug with the overlays library that means structured overlays don’t work well at this moment, so use targeted overlays).

Use overlayjs to update the API description

Check the installation instructions to get the tool installed if you don’t have it already.

Run the command and supply the API description as --openapi and the overlay as --overlay. For example, the following command applies overlay.js to openapi.js:

overlayjs --openapi openapi.yaml --overlay overlay.js > new-openapi.yaml

The command writes to stdout, so you can direct the output wherever you would like it to go. In my case, I’ve directed it to a file called new-openapi.yaml.

Take a look at the updated OpenAPI description, or diff it against the original, and you should see that the post endpoints now have the OpenAI x-openai-isConsequential: true added.

By using OpenAPI Overlays, you get a standard format and a choice of tools to apply it with. You can prepare an OpenAPI file for use with OpenAI, even if you are an API consumer and have no input into the way that the OpenAPI is created – or if you just want to avoid cluttering other stages of your API lifecycle with the metadata specific to the OpenAI use case. Hopefully this helped you get your OpenAPI in shape for OpenAI (yes, still confusing to have such similar words!), I’d be happy to hear how you get on if you want to share in the comments.

Version your API Descriptions

Let’s start with: please, please do use the version field, and update it from time to time. In OpenAPI, the version of the description is in the info.version field and the official documentation describes it as:

REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

To break this down, the documentation describes what the version field is, and also two things that it is not:

• it is the version of the OpenAPI document.
• it is not the version of OpenAPI specification being used (this is in the top-level openapi field).
• it is not the version of the API that it relates to (many descriptions cover multiple API versions, and may also change without the API changing).

So now we’ve cleared this up for OpenAPI, and pretty much everything here applies to AsyncAPI as well, let’s think about when the version should change.

When to update the API description’s version field

TL;DR when the API description changes, update the version field.

The whole point of a version field is so that I can tell if I have the most recent version of your API description, or which version something used. So if the two things aren’t the same, then probably their versions shouldn’t be the same either.

Some things that should probably cause a version change:

• a new endpoint was added to the API, or something was marked as deprecated
• the description was updated to include improved summaries, descriptions, tags or examples
• the description was restructured

Having a process that publishes a new OpenAPI description with an updated version is something you’ll want to be able to do easily and regularly, so make it painless to do.

A note on version formats: OpenAPI only recommends a string. Many organisations do use a SemVer approach, and this is well understood by technical audiences, but choose something that fits you. Take a leaf out of Stripe’s book and use dates for versions, for example. Whatever you choose, don’t get bogged down in what does or does not require a new release. Make new releases easy and aim for releasing too often rather than too infrequently!

This quick roundup on API versioning was the result of having this conversation several times over the last few weeks/months, with people all over the API ecosystem. We talk a lot about API versioning, but not nearly enough about API description versioning, so I wanted to share some thoughts and most of all encourage everyone to version their API descriptions (at all! With any sort of version!) and to update those version fields from time to time :)

Are there any organisations or APIs you’ve seen that do this particularly well (or badly, if you can be constructive about why it’s not working)? I’d be interested in seeing comments pointing to more examples of what you have spotted in the wild.

OpenAPI in a GitHub repo

API documentation using OpenAPI assumes a docs-as-code workflow, and so does this post. You should have an OpenAPI description in a GitHub repository, so that when the description changes, the documentation can update. The big win here is that by adding preview builds for all pull requests, incoming changes can easily be shared and reviewed by all stakeholders, without any need to read YAML.

Tip: there’s no need to bundle the OpenAPI description to a single file, Redoc will follow references across files as needed so this approach is ideal for the during-development-and-review phase of the process.

Configure the Netlify project

The basic process, for Netlify or any equivalent, is to link the GitHub project to a deployable project so that updates run every time the repository updates. Netlify needs to know how to build the project, which in this case is generating the documentation as HTML, and what to publish. There’s a setting for “do this for pull requests as well” which is what makes the whole thing seem like magic!

Get started with the “Add new site” option and choose “Deploy with GitHub”. You may need to link your Netlify account to your GitHub account and/or the project you want to use if you haven’t used these tools together before or if you grant access on a per-project basis. Once that’s done, pick the project to generate API documentation for.

The next screen sets the site configuration. My project has openapi.yaml in the root folder, and my settings are like this:
* The build command is npx @redocly/cli build-docs openapi.yaml -o build/index.html.
* And publish directory is set to build/ since that’s where the previous command writes the files to.

Save the settings and the project will (hopefully) deploy successfully – don’t look away, it’s fast!

I’m not sure when Netlify started enabling preview deploys by default but that’s the behaviour in my most recent new site. Test your own setup by making a small but identifiable change to your API description, committing the change to a branch, and opening a pull request. After a few minutes the Netlify bot should comment with a link to the preview of the updated documentation.

All in all, the time investment to get a basic documentation rendering is definitely worth it (and if you need something more then I think I am contractually obliged to suggest you check out Redocly for the rest of the products). Investing in every stage of your API pipeline, from linting, to enrichment, and to docs – delivers rewards. And delivers them every time you make an API description change!

Hopefully you found this useful, I’d love to hear if you set this up yourself, or if you can share equivalent setups for other platforms so that others can learn from your wisdom: add a comment!

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!

Most of Vale’s configuration uses a .vale.ini file, but you specify the files and directories to check at the time you run the command, with something like:

vale docs/

In my case, I needed to exclude a mix of folders (there’s little value in checking/fixing a meeting notes collection of a past project, and we can’t make changes to our legal docs. Also there’s a page of good restaurants near the office that is full of proper nouns!). To include just one section or another, I could run Vale multiple times to check each section, but to run everything except some problem areas, I used --glob. I ended up with a command like this:

vale --glob='!{office/where-to-eat.md,legal/*,projects/codename/meetings/*}

Some of the skipped directories we will probably work on improving and then dropping the exception for – but this approach is useful when retrofitting a tool like Vale to an existing repository which can’t be made to align all at once. We’re also using a pretty reduced ruleset and may incrementally add to this over time.

Glob in GitHub Actions

Probably all the CI integrations have something similar but Vale has a GitHub Action and I could add the whole --glob expression to a vale_flags entry in the with step.

Ideally we’d be running identical commands and configuration both locally and in CI, but since the configuration for this doesn’t seem to be able to go in the Vale config file, I compromised on adding it as an npm script as well as a GitHub action. It’ll be annoying to maintain but I didn’t come up with any better ideas!

Hopefully this post will help me next time I’m wondering how to combine glob expressions for Vale, since I didn’t find many other examples. If it helps you do, then that’s even better! Share your tips in the comments :)

The hardest part was (as always!) getting started with an unfamiliar toolchain, knowing what to edit, how to serve the file, and if there was an extra step needed to see changes. The developer documentation for Blockly is very good, and I tried to follow their guidelines as much as I could. I ended up writing a messy web page that had a textarea that I could use to import/export what I’m working on, and writing it all to local browser storage – because every time I changed the toolbox, I lost the data structure I had just built!

It’s not a complete library, but it did allow me to create the visuals I wanted for my talk “OpenAPI for Documentarians” at APItheDocs in Amsterdam, and I think it’s likely that I’ll expand and use this again. I got positive feedback from trusted audience members, and a few people told me they found it “approachable” – which is exactly what I was aiming for.

I’ve published the whole project on GitHub, and I’d be happy to have forks, contributions, suggestions or feedback on this. There are places where I think there’s probably better ways to represent some elements, for example. Also the idea of Blockly is that it’s a high level language that can then be compiled to something for the machines when the humans have finished with it. I’m not sure if it’s even possible to write the converters for it to output OpenAPI but that would be a really fun project if anyone is up for it :)

If you use it, I’d love to hear about it – drop me a comment!

Summary vs description

OpenAPI supports both summary and description fields and they’re both strings that contain information about the thing they are attached to, such as a parameter, endpoint, schema, or response. So which do you use?

Summary is a plain text field, and should typically be shorter: just one or two sentences. It’s often used when listing elements, although different tools render different tools differently, so always check what your tools product and do whatever looks right there.

Description fields support markdown, so this presents an opportunity to link to additional information or documentation. Particularly in the top-level info.description field, this can be an opportunity to write multi-paragraph detailed overview documentation.

Good description fields give context

It’s very common to see a description for the user_id field which says something like “the ID of the user”. Um, thanks?

Everyone can do better than this – and if you’ve ever had to read API documentation from someone else, you know how much difference it makes. I advise people to ask themselves WHAT this field/endpoint/whatever does, and WHY it’s needed. Think about what the user is doing when they use this endpoint, and give a bit more context. Something like “the ID of the user placing the order. This value can be found in the order detail object or order status update object. Find the current user’s ID by going to /user/me`. You get the idea. Context is everything!

Taking pride in API documentation is a Developer Experience multiplier; just make sure that everyone working on your API documentation knows how much you value the extra effort in this area, and that it is something that collaborators should spend time on.

Simplest styleguide

Writing brilliantly is absolutely an art, but writing well enough is attainable for everyone. My advice is always to keep it simple and informative.
* Use short sentences
* Use present tense (the endpoint “does” something, rather than “will do” the thing)
* If you can remove extra phrases, such as “in this case”, do so. It keeps things easier to read
* Be kind. Keep things gender-neutral and inclusive, and avoid belittling words such as “simply” and “just”

With these in mind, you won’t go far wrong. Engineers can absolutely be brilliant at this without formal training.

Markdown in YAML

Description fields support markdown, which is brilliant, and allows expressive additions if you need them. If you use YAML for OpenAPI documents, there are a couple of additional operators that can make it much easier to work with.

Folded block starts with >. This is great if you just want to wrap your content to make it manageable, or compatible with the linters/formatters you use on the file. I quite like to use a one sentence per line format for markdown, because it makes diffs more readable, and this works nicely with that approach.

description: >
  This is a folded block style in YAML.
  It preserves line breaks but ignores leading
  and trailing white spaces.

Literal block starts with |. Use this approach if you have markdown that uses whitespace, such as titles or bullet points.

description: |
  # Title

  This is some Markdown content.
  It can include multiple paragraphs,
  lists, headers, and other Markdown syntax.

Using the appropriate markdown syntax can make things much easier and maintainable over time.

Link to external documentation from API reference

I don’t often see the externalDocs used but it’s a top-level element in OpenAPI that is designed to make the main API documentation (landing pages, quickstarts, tutorials, etc) easily findable from the API reference documentation. Additionally, OpenAPI tags, schemas and operations all also support externalDocs properties, so you can link directly to detailed documentation for any of those elements too. Especially useful when there’s a lot of information to include, that can be unwieldy in the description fields.

What are you tips for getting the best documentation from OpenAPI? I’m working full time in this space now (at Redocly, and really enjoying having lots of conversations about docs, APIs, and everything in between! ]]> https://lornajane.net/posts/2023/tips-for-better-documentation-with-openapi/feed 0 4621