DEV Community: Andrew Owen

Creating an API style guide

Andrew Owen — Sun, 06 Apr 2025 12:55:30 +0000

I was recently asked for my favorite resources and best practices for writing clear and structured API docs. I've developed my own style for writing API docs, but up until now I haven't published it. Although I've mainly worked with REST APIs, this guidance applies equally to GraphQL and any other APIs. But before I get to writing style, the most important requirement for good API docs is a good API. If you're using REST, validate it with Stoplight. If endpoints are inconsistent in how they handle common parameters, there's no way to write around the problem. This seems to be more of an issue with REST and may account for the move away from REST toward GraphQL. The next thing that you need is static, searchable docs. Don't expect your GraphQL users to find the information they need by browsing your schema in Apollo. Don't expect your REST users to scroll to the bottom of the Swagger UI page to find out how to format data for a given endpoint. If you need a no-budget solution, Redocly CLI and Magidoc are good places to start for REST and GraphQL respectively. Unless you use AWS hosting (which doesn't play nicely with Magidoc's clean URLs). And don't think that you're done when you've published your schema. Developers need workflows, code examples and reference information to understand how they are expected to use your API. Ideally, this information should live in a public developer portal. Your rivals are not going to be able to clone your product by examining your API. And even if they start adding features based on it, you'll always be several steps ahead.

General style guidelines

When I became an API writer I found that, just like other software, docs are often an afterthought. But if you want people to use your APIs, they need to be well documented. However, API writing isn’t the same as traditional technical writing. Use a terse, factual writing style. Sentence fragments are desirable. Avoid adjectives and adverbs. You need to provide:

Complete information about each API component.
Contact details in case developers have questions or require additional assistance.
Flow charts showing the sequence of the most commonly used methods for common use cases.
Getting Started guides showing how to develop a program for a common use cases.
Performance and tuning information.
Sample programs demonstrating common use cases.
Working code snippets for each method, function, and resource. You don’t need complete examples, but show a common use of that element.

Unless you are writing exclusively for an internal audience, use American English and don't translate your API schema. The language should be simple enough for a developer to follow without requiring translation.

Endpoint names

lower case (except initialisms and acronyms)
descriptive (action—objects—criteria)
as brief as possible
active voice
use CRUD for the action (create, read, update, delete)
include all match criteria (example: by user or ID)

Example: read API key by ID

Endpoint descriptions

Sentence case.
descriptive (action—objects—criteria)
brief sentences
passive voice
human readable actions. Example:
- POST: Creates
- GET: Retrieves
- PUT: Updates
- DELETE: Removes

Example: Retrieves details of a registered API key for the current user by ID.

Parameters

human readable
brief
provide examples
link to relevant standards

Example: expiry: Expiry date (ISO 8601 format)

Responses

list all expected responses
for REST provide at least the minimum boilerplate text for each response

Example: 404 Not found: The URI isn’t valid, or the requested resource doesn’t exist.

REST specific guidelines

I've documented the principles of REST APIs elsewhere. No-one follows them, which is why APIs are described as RESTful. HTTP methods should be used consistently for specific tasks.

Method	CRUD	Typical response code
POST	Create	201 Created
GET	Read	200 Success
PUT	Update	202 Accepted
DELETE	Delete	204 No Content

The other HTTP methods are:

HEAD — Almost identical to GET, but without the response body.
OPTIONS — Describes the communication options for the target resource.
PATCH — Applies partial modifications to a resource.

I would recommend avoiding these three in public APIs, although you may have reasons to use them internally.

Boilerplate text

One of the limitations of the current generation of Markdown and REST API doc tools is that they have little to no support for automated content reuse. For that reason, you should keep a list of standard definitions and valid payload examples. For example:

Address — Use your company’s main address.
Barcode — 019000000002 (UPC-A format including check digit)
Brand — Ownbrand (too generic to be registered as a trademark)
Country — USA (ISO 3166-1 alpha-3 format)
Credit card number — 4111111111111111 (Use any CVV, NAME and future EXPIRY DATE. Keep purchase value under $500. https://docs.stripe.com/testing)
Currency — USD (https://www.iso.org/iso-4217-currency-codes.html)
Date time offset — 2019-11-01T00:00:00-05:00 (https://en.wikipedia.org/wiki/ISO_8601, use long version to avoid ambiguity)
Debit card number — 6304000000000000 (bank card number with the defunct Laser identifier)
Email — username@example.com (example.com is reserved for examples)
First name — Don’t use other terms for first name. In some cultures, the family name precedes the given name.
GUID — 01234567-890a-bcde-f012-34567890abcd
Last name — Don’t use other terms for last name. In some cultures, the family name precedes the given name.
Telephone — +1 202 555 0199 (555 numbers ending 0100-0199 are fictitious)
URL — www.example.com (example.com is reserved for documentation)

HTTP response codes

You should provide as much response code information as possible. The minimum acceptable level of documentation is the number, a meaningful short description and an explanation for typical use cases.

1xx: information

100 — Continue.
101 — Switching protocols.
102 — Processing.
103 — Early hints.

2xx: success

200 — Success: Object created or fetched.
201 — Created: Object created or replaced.
202 — Accepted: Processing asynchronous request.
203 — Non-authoritative Information.
204 — No content.
205 — Reset content.
206 — Partial content.
207 — Multi-status.
208 — Already reported.
226 — Instance-manipulations used.

3xx: redirection

300 — Multiple choices.
301 — Moved permanently.
302 — Found.
303 — See other.
304 — Not modified.
305 — Use proxy.
306 — Switch proxy.
307 — Temporary redirect.
308 — Permanent redirect.

4xx: client errors

400 — Bad request: The request wasn’t valid or can’t be otherwise served. Typical when there is a syntax error in the request. Further details of the error are provided in the response payload body.
401 — Unauthorized: Missing or incorrect authentication credentials.
402 — Payment required.
403 — Forbidden: The request is understood, but it was refused or access was denied. The response payload body provides further details of the error.
404 — Not found: The URI isn’t valid, or the requested resource doesn’t exist.
405 — Method not allowed: The requested resource doesn’t support the method.
406 — Not acceptable.
407 — Proxy authentication required.
408 — Request timeout.
409 — Conflict.
410 — Gone.
411 — Length required.
412 — Precondition failed.
413 — Payload too large: The request is larger than the server is able to process.
414 — URI too long.
415 — Unsupported media type.
416 — Range can’t be satisfied.
417 — Expectation failed.
418 — I’m a teapot (don’t ask).
421 — Misdirected request.
422 — Entity can’t be processed: The request was well-formed, but the data couldn’t be processed due to semantic errors.
423 — Locked.
424 — Failed dependency.
425 — Too early.
426 — Upgrade required.
428 — Precondition required.
429 — Too many requests.
431 — Request header fields too large.
451 — Unavailable for legal reasons.

5xx: server errors

500 — Internal server error: This is usually a temporary error, for example in a high load situation or if an endpoint is temporarily having issues.
501 — Not implemented.
502 — Bad gateway.
503 — Service unavailable.
504 — Gateway timeout.
505 — HTTP version not supported.
506 — Variant also negotiates.
507 — Insufficient storage.
508 — Loop detected.
510 — Not extended.
511 — Network authentication required.

Getting started with GraphQL

Andrew Owen — Sun, 06 Apr 2025 12:53:05 +0000

GraphQL is an API query and manipulation language. Created by Facebook in 2012, it was open-sourced in 2015. In 2018 it moved to the GraphQL Foundation and introduced a schema definition language (SDL). It seems to be replacing REST as the standard way to expose public APIs. With REST, you have to define the inputs and outputs for each endpoint. Whereas with GraphQL, there's only one endpoint and you define a schema. The user sends only the required data to get what they want back. And unlike SQL, you're not limited to a single data source.

This year, I've had to get rapidly up-to-speed with GraphQL. I thought I'd be starting from nothing, but I'd forgotten that TinaCMS (the headless content management system that I use with this site) uses it. One of the first problems I had to solve was how to generate static documentation. My limited research led me to two possible solutions: SpectaQL, developed from the earlier DociQL, and Magidoc. The latter has built-in search, so that made my choice for me. I use Hugo as my static site generator, so the first thing I had to do was start the local version of TinaCMS from my site's Git repository:

npx tinacms dev - c "hugo server -D -p 1313"

With the local server running, you can access GraphiQL at http://localhost:1313/admin/#/graphql. GraphiQL is a reference implementation of the GraphQL API playground. If it's too basic for you, there's a commercial alternative called Apollo. The TinaCMS implementation gives you three options (selected from the icons on the left):

Docs: API docs in a tree structure.
History: Previous queries.
Queries: Query builder.

After you've taken a look at the Docs section in GraphQL, you'll understand why I wanted to generate a static site. With Magidoc it's easy. I added this configuration file to my Git repository:

export default {
  introspection: {
    type: 'url',
    url: 'http://localhost:4001/graphql',
  },
  website: {
    template: 'carbon-multi-page',
      customStyles: ['/static/css/custom.css'],
  },
}

Then to generate the documentation, enter: pnpm add --global @magidoc/cli\@latest && magidoc generate (you'll need pnpm installed). By default, this creates a static site in a folder called docs. However, you can't just open the index.html file. You'll need to launch the server with magidoc preview and then follow the link. You may want to add the docs folder to your .gitignore file. But in production, you can deploy using any web server. The output is based on IBM's Carbon Design System.

Now you've got some static searchable documentation, you can start exploring your schema. GraphQL schema can be written in any programming language that implements the type system. With TinaCMS that means either TypeScript or JavaScript. Here's a snippet of my Tina config.js file:

    schema: {
      collections: [
        {
          name: "blog",
          format: "md",
          label: "Blog",
          path: "content/blog",
          defaultItem: () => {
            return {
              draft: true,
            }
          },
          fields: [
            {
              name: "draft",
              type: "boolean",
              label: "Draft",
              required: true,
            },
            {
              name: "title",
              type: "string",
              label: "Title",
              isTitle: true,
              required: true,
            },
            {
              name: "date",
              type: "datetime",
              label: "Date",
            },
            {
              name: "description",
              type: "string",
              label: "Description",
            },
            {
              name: "image",
              type: "image",
              label: "Image",
            },
            {
              name: "image_license",
              type: "string",
              label: "Image License",
            },
            {
              name: 'tags',
              type: 'string',
              label: 'Tags',
              list: true,
            },
            {
              name: 'body',
              type: 'rich-text',
              isBody: true,
              label: "Body",
              templates: [
                {
                  name: 'shortcode',
                  label: 'shortcode',

This creates a schema type called Blog with the fields:

draft: Boolean!
title: String!
date: String
description: String
image: String
image_license: String
tags: [String]
body: JSON
id: ID!
_sys: SystemInfo!
_values: JSON!

Fields can be scalar (Boolean, Float, Integer, String and so on) or complex (containing other data). A trailing exclamation mark ( ! ) means the field is required (non-nullable). Square brackets mean an array. If the type is JSON, then a set of sub-fields is defined. You can also use previously defined types to create relationships. For example, if your blog has multiple contributors you could have a field called author with the type User!.

Queries

Because there's only one endpoint, you have to tell it what you want. For example, to get the list of collections you'd use:

{
  collections {
    name
  }
}

The collections filed is the root field. Everything else is the payload. Because the payload only contains name the query returns a list of all the collections:

{
  "data": {
    "collections": [
      {"name": "blog"},
      {"name": "recipe"}
    ]
  }
}

You get exactly the amount of information you ask for in the payload. You can also pass arguments. For example, if you wanted to get the title, date and draft status of this article you could use:

{
  blog(relativePath: "getting-started-with-graphql.md") {
    title
    date
    draft
  }
}

However, typically you would use a variable in the query, like this:

query blog($relativePath: String!) {
  blog(relativePath: $relativePath) {
    title
    date
    draft
  }
}

Variables have a prefix ( $ ). The type (String in this example) is defined in the query. The variable is passed in the blog parameters.

Mutations

Query is the equivalent of GET in REST or read in traditional data terminology. For create, update and delete there's mutation. The syntax is the same as for queries. You might have noticed the ID type earlier. If you specify it when creating a record, the GraphQL server will give it a unique identifier. You can try out this example from the TinaCMS documenation (sticking with the Napoleon Dynamite references):

mutation {
  updatePost(relativePath: "voteForPedro.json", params: {title: "Vote For Napolean Instead", category: "politics", author: "content/authors/napolean.json"}) {
    title
    category
    author {
      ... on Author {
        id
      }
    }
  }
}

Subscriptions

I've written previously about event-driven architectures. Subscriptions are a way to get data from the GraphQL server every time an subscribed event takes place. Not all GraphQL servers are configured to support websocket subscriptions, and that's true of my TinaCMS instance. But if it was, this is what a request to be notified when a new blog article is created would look like:

subscription {
  newBlog {
    title
  }
}

Custom scalars

Five months after I originally wrote this article, I ran into an issue with Magidoc. The doc build was failing with missing definitions for custom scalars. At first, I thought this was a bug, but it turns out that the bug was that the previous version would build the docs even if the definitions were missing. You don't need to provide definitions for the predefined scalars (String, Int, Float, Boolean and ID). But if you have any custom scalars in your schema you must provide an example for each in JSON format in the Magidoc config file. These definitions go under options in the website section:

  website: {
    template: 'carbon-multi-page',
      customStyles: ['/static/css/custom.css'],
    options: {
      queryGenerationFactories: {
        accountID: "01234567-890a-bcde-f012-34567890abcd",
      }
    }
  }

Conclusion

It's beyond the scope of this article to do more than cover the basics. For more information, the GraphQL documenation is a good starting point. TinaCMS is a good application to start experimenting with its GraphQL API. For the adventurous, Kingdom Orjiewuru wrote the first part of an article on building a simple document manager with GraphQL.

Why you should try programming in Lua

Andrew Owen — Sun, 06 Apr 2025 12:49:15 +0000

Let me start by saying that I don't have anything against Python. It's the number one programming language for a reason. But I learned Perl before Python was invented, and I've never had a compelling reason to learn it. On the other hand, when I worked in video games, I needed to get familiar with Lua and I found it very much to my liking.

Lua (meaning moon in Portuguese) is 30 years old this year. It was created by Waldemar Celes, Luiz Henrique de Figueiredo and Roberto Ierusalimschy at the Computer Graphics Technology Group of the Pontifical Catholic University of Rio de Janeiro. Brazil's trade barriers for computer software and hardware meant that it was natural for the department to create its own efficient, lightweight, embeddable scripting language.

In its current version, Lua supports data-driven, functional, object-oriented and procedural programming. It combines simple procedural syntax with data description constructs based on associative arrays and extensible semantics. It's dynamically typed, runs by interpreting byte code with a register-based virtual machine and has automatic memory management with incremental garbage collection.

During the seventh console generation (PlayStation 3, Wii, Xbox 360), one games industry survey found that more than half its respondents were using Lua for scripting. This makes a lot of sense when you consider that the leading game engine at the time was Unreal, and the leading game development language was C/C++. More than a fifth of respondents were also using Lua for rapid prototyping. Not only is Lua fast, portable, embeddable, simple but powerful, it's also small at around 30000 lines of code. And it's distributed under the MIT License.

When parents decided to teach their kids programming, they will often start with block-based languages like Scratch. These can teach programming principles and generate an enthusiasm for programming. But prolonged exposure could make it harder to transition to line-based programming. Python is a popular choice of teaching language, except with mean Gen X parents who make their kids use BASIC. Lua is a little more niche, but it has some cool add-ons like the Lapis web framework and the LÖVE 2D-games framework, and it's used in some interesting places:

There are two commercial projects I'm particularly fond of. For iPad owners, Codea gives you a way to develop apps directly on the device. It was created by University of Adelaide PhD students John Millard, Simeon Saëns and Dylan Sale. It's mainly aimed at games development, but it can be used for general purpose apps too. Complete projects can be exported directly into Xcode. It supports 3D through voxels and models in Wavefront format (as exported by Blender). Its frameworks include animation, graphics, location, motion, multitouch, network, physics, sound and storage. The first ever app store app made entirely on the iPad was made with Codea. Although currently, the only featured game still available is Cargo-Bot. It has comprehensive documentation and comes with sample projects to get you started.

For people who like the retro aesthetic but don't want to learn 6502 or Z80 assembly language, the Pico-8 is a fantasy console that runs in a web browser or on Linux, macOS and Windows. It has a 128×128 pixels display with 16 colors from a palette of 256 colors. There are 256 8×8 pixel sprites and a 128×32 tile map. It has a 4-channel programmable sound generator. There are editors for code, music, sound, sprites and maps built into the console. Cartridges are stored as PNG files. Pico-8 also includes licensing for educators.

Afterword

As is often the case, I learned about another project after publishing. The TIC-80 is an open source alternative to the Pico-8 that also ssupports Lua. It too has built-in editors for code, sprites, maps, sound and so on. It has a 240×136 pixel display with a fixed 16 color palette that is quite similar to the DawnBringer 16 palette. The TIC-80 has proved particularly popular at in the computer demoscene.

An introduction to the semantic web

Andrew Owen — Sun, 06 Apr 2025 12:47:18 +0000

One of my predictions for 2023 was that there would be a lot more talk about Web 3.0. I couldn't have been more wrong. Global events and the rise of AI have completely overshadowed web developments. But it's still a topic worth some consideration.

The term Web 2.0 was coined by Darcy DiNucci in 1999. Web 1.0 was subsequently invented as a term to describe the earlier period. There is no fixed delineation between the two eras. The first is generally thought to have lasted from 1989 to 2004 and featured mainly static content. The second is thought to start when social media profiles replaced personal web pages.

But I'd draw a different distinction. I think of Web 1.0 as everything before HTML5 (or the Flash era). When the iPhone was announced in January 2007, initially it wasn't supposed to run native apps, except for the basic set included on the device. It was supposed to run web apps (written with Ajax). HTML5 launched the next year.

Web 3.0 means different things to different people. It's sometimes used as an alternative term for Web3, which is an idea for a version of the web featuring decentralization, blockchain and token-based economics. It's where non-fungible tokens (NFTs) came from. But it's not well-defined or widely adopted.

In his 2000 book “Weaving the Web”, Tim Berners-Lee described a vision where computers:

The semantic web is also sometimes known as Web 3.0. But Berners-Lee wasn't the first to have this vision. Arguably, it started with Ted Nelson and Project Xanadu in 1960. And the ideas that influence it can be traced back even earlier to Vanneavar Bush's 1945 article “As We May Think”. For a deeper dive I recommend watching Douglas Adams's 1990 documentary “Hyperland” which predates the World Wide Web and the first web browser.

Hyperland does a remarkable job of predicting the modern internet, developments in virtual reality and software agents like Siri (although Tom Baker's agent is rather more configurable). But I'm in the minority camp that thinks that Xanadu would have been better than what we have now. Its original rules stated that every document can:

Consist of any number of parts, each of which may be of any data type.
Contain links of any type, including virtual copies to any other document in the system accessible to its owner.
Contain a royalty mechanism at any desired degree of granularity to ensure payment on any portion accessed, including virtual copies of all or part of the document.
Have secure access controls.
Be rapidly searched, stored and retrieved without user knowledge of where it is physically stored.

Every server, user, document and auditable transaction would be uniquely and securely identified. Documents would automatically be moved to physical storage appropriate to frequency of access from any given location. Documents would automatically be stored redundantly to maintain availability even in case of a disaster. Blockchain will have a role to play if we ever get there.

That leaves us with the semantic web, which exists now. But what are semantics? The term is derived from the earlier semiotics (the interpretation of signs and symbols). It can mean the study and classification of changes in significance of words, or a branch of semiotics to do with relations between signs and what they refer to. But in web terms, we'd probably just call it metadata.

One way of adding metadata to web pages is using the Open Graph Protocol. It was originally developed by Facebook (Meta) for use with its Social Graph mapping and tracking tool. Meta uses it to enable any web page to have the same functionality as any other object on Facebook. But other social networks also use it. The basic metadata includes:

og:title Title of the object as it should appear within the graph. Example: “The Rock”.
og:type Type of object. Example: “video.movie”.
og:image Image URL that should represent your object within the graph.
og:url Canonical URL of your object that will be used as its permanent ID in the graph. Example: “https://www.imdb.com/title/tt0117500/”.

On this site with Hugo, I include these tags in head.html partial:

<meta property="og:title" content="{{.Title}}" />
<meta property="og:type" content="article" />
<meta property="og:image" content="{{.Params.Image | absURL}}" />

This means that when you click one of the social share buttons, it should pick up the correct image. Before I did this, it would default to the background that goes behind the header.

Tags have long been used for search engine optimization (SEO). Here are some commonly recommended tags to include in the <head> tag on an HTML page:

<title>A clickbait title</title>
<link rel="canonical" href="https://example.com/">
<meta name="description" content="A description of the content." />
<meta name="author" content="Your Name" />
<meta name="viewport" content="width=device-width, initial-scale=1" />

The viewport tag ensures the browser window is an appropriate size for the screen of the device. You should also include <meta name="robots" content="noindex"> on pages that you don't want to be indexed, such as error pages. And you should always include the alt attribute on images. But you can go much deeper and add microdata to your content with schema.org.

To conclude, while we're waiting for Web 3.0 to arrive, it's a good idea to start using metadata. If nothing else, it will be useful to our future robot overlords.

Getting started with Bitbucket Pipelines

Andrew Owen — Sun, 06 Apr 2025 12:43:26 +0000

I'm a big fan of GitHub Actions. But if you're working for an enterprise software company, there's a fair chance you're using Atlassian's Bitbucket Cloud (along with Confluence and Jira). If so, then you can use Pipelines to build continuous integration and deployment workflows. If you're new to DevOps and CI/CD, I have a TL:DR for you.

In Bitbucket, go to your repository and select Pipelines.
Click Create your first pipeline to scroll down to the template section.
Select the Starter pipeline. This will create a file called bitbucket-pipelines.yml.

Previously, I wrote a GitHub Action to unpack a zip archive. So let's recreate that:

image: atlassian/default-image:3

pipelines:
  default:
    - step:
        name: 'extract a zip file'
        condition:
          changesets:
            includePaths:
              - "*.zip"
        script:
          - rm -r uploads/extracted
          - filename=$(basename -s .zip *.zip)
          - unzip *.zip
          - rm *.zip
          - mv $filename temp
          - mv temp/out/* .
          - rm -r temp
          - git add .
          - git commit -m "unzip"
          - git push origin main

When you're done, click Commit File.

Bitbucket Pipelines runs your builds in Docker containers. So first you need to choose an image. The default is atlassian/default-image:latest. Atlassian recommends using this until you get your pipeline working and then finding a specific image. So in this instance, we're using Ubuntu 20.04 LTS.

default tells the script to run when a commit is pushed to any branch.
parallel enables you to run steps simultaneously, but it's not necessary here.
step is an individual task.
name is the display name of the step.
condition limits the circumstances under which the script runs.
changesets specifies changes to use as a condition.
includePath sets the file path that will match the condition.
script is the Linux CLI input.

The script is virtually identical to the GitHub Action I wrote, so for a more detailed explanation, you can read that.

Image: original by Sigmund.

Adding languages to a Hugo site

Andrew Owen — Thu, 16 Mar 2023 08:44:33 +0000

I'm a long-term advocate for localization, but this site has been monolingual for over a year now. It's past time I started following my own advice. So last weekend I finally got around to localizing the site for French.

As with most localization tasks, I'm retrofitting it to an existing project. Fortunately, I chose Hugo as my static site generator, and it has built-in internationalization support using go-i18n. On the downside, I chose a theme that doesn't fully support localization, which meant there was some work involved. But not as much as I'd expected. So let me take you through the steps involved.

First, I updated my config.toml file to tell Hugo that my site is now multilingual:

defaultContentLanguageInSubdir = false
DefaultContentLanguage = "en-us"
[languages]
  [languages.en-us]
    title = "Andrew Owen | Writer | Designer"
    languageName = "English"
    weight = 1
  [languages.fr]
    title = "Andrew Owen | Écrivain | Concepteur"
    languageName = "Français"
    weight = 2

Setting defaultContentLanguageInSubdir leaves the language out of the URL for the default language, in my case US English. Any settings you leave out from the language definitions will fall back to the default.

My 404.md page is already stored in a folder called en. So adding a French version was just a case of creating a new folder called fr, copying the file across and changing the text.

The next step was to set up some a set of translatable phrases for the generated content. This is as simple as creating an i18n folder in the root of the Hugo repository and adding a YAML or TOML file for each language. In my case en-us.yaml and fr.yaml. These phrases are included using the shortcode {{T "phrase" | formatting}}. If you want to include HTML such as <br> tags, then use safeHTML for the formatting value. Each value should have an ID and a definition in each language file. For example:

- id: January
  translation: "janvier"

In several places in the site, titles were derived from data contained in YAML files. In each of these cases, I replaced the data-derived version with a shortcode to the translated version instead. I also had to modify some of the links to go to the correct place when viewing the site in French. In most cases, that just meant using the .Site.Language.Lang value.

Because I'm only supporting two languages, I wanted to have a simple toggle. The nav bar was starting to get rather full, so I removed the Home link, because the logo already takes you there. I had to change the RSS link to make it work in French, so I also replaced it with the icon. I figure anyone who still cares about RSS should recognize it:

<li class="nav-item">
  {{ if eq .Site.Language.Lang "en-us" }}
  <a class="nav-link" href="/blog/index.xml"><i class='fa fa-rss'></i></a>
  {{ else }}
  <a class="nav-link" href="/fr/blog/index.xml"><i class='fa fa-rss'></i></a>
  {{ end }}
</li>

The last thing to do was to translate the individual articles. Hugo gives you two ways of doing this. You can set up a folder for each language, and if you have three or more languages, you should do this. But by default, Hugo will treat anything ending in .md as the default language, and you can add other languages by adding the language code to the extension, for example: .fr.md. If you're using folders, then you add the folder details to the language definitions in your TOML file. For example:

[languages]
  [languages.en]
    contentDir = "content/english"

While I was editing the site in VScode, I also took the opportunity to reorganize the images. They were getting a bit tricky to navigate with TinaCMS, so I moved the blog images into folders by year. I also did some cleanup on the top nav bar. The last thing to do was change the article date string from {{ .PublishDate.Format “2 January 2006” }} to {{.Date.Day}} {{i18n .Date.Month}} {{.Date.Year}} after setting up a set of translatable date strings in the YAML files in the i18n folder.

Of course, just when I thought I'd caught everything, I noticed that tag links were broken. I fixed this by making the URL relative so that it would pick up the current language. I'm pleased to say that I didn't have to do anything at all to localize search.

With the technical piece done, all that's left to do is the translation. There are ways to automate the process, but there's still no substitute for a human reviewer. I'm using a combination of DeepL, LanguageTool and my own modest language ability. To begin with, I'm only translating the core content. But eventually I intend to have a fully translated site. If you are a native French user, and you spot any egregious mistakes, please drop me an email.

Sales for developers

Andrew Owen — Thu, 19 Jan 2023 06:59:41 +0000

You're a developer. Have you ever wondered how the software you write gets into the hands of users? No, me either. In over 15 years in IT, I never gave a thought to the sales process. But in my role as a solutions engineer, I've had to take a crash course. And now I'm convinced that everyone who isn't sales should at least understand something about it. Fortunately, my MasterClass subscription is still valid, so I was able to take Daniel Pink's class on Sales and Persuasion. Previously, I watched the entire John Barrows YouTube sales tips playlist (if I hear someone say “make it happen” one more time, I'm going to scream). But unless you work at one of those companies where you're told “everyone is in sales”, you probably don't want to spend half a day watching those. So I'll reduce it down to the essentials for you.

Evaluating a prospect

In the 1950s, IBM came up with a sales strategy known as BANT that's still in use today:

Budget: Can the organization you're selling to afford what you're selling?
Authority: Can the person you're dealing with approve the purchase?
Need: Does what you're selling solve the organization's problems?
Timeline: When will a purchase decision be made?

If they can't afford or don't need what you're selling, thank them for their time and move on. If your contact can't approve the purchase, involve the person who can. If the decision is more than a year away, park it for now and revisit closer to the time.

Consecutive selling

It's time for another acronym. In the 1980s, Neil Rackham came up with a series of questions to use in large sales deals known as SPIN-selling that's still in use today:

Situation: Ask about the pain points and expectations to determine goals and needs.
Problem: Ask leading questions to identify problems, such as “how much time a day do you spend on that?”
Implication: Ask about the consequences of the problems, such as “how much time does that waste a month?”
Need-payoff: Ask questions to lead the prospect to their own positive conclusions, such as “if you could be more productive, what effect would that have on your revenue?”

There are four stages, but no acronym this time, unless you mistype PAID:

Preliminaries: Introduction. Don't talk about your product or service.
Investigation: Situation questions. Don't talk about your product or service.
Demonstration of capabilities: Implication and Need-payoff questions. Talk about your product or service in terms of (another acronym) FABs: “Product [feature], enables you to [advantage] which means you get [benefit].”
Acquiring commitment: Close the deal. Ideally, set a date for a yes / no call.

The new rules

“Glengarry Glen Ross” is a great film. But it's a terrible way to sell. Sellers used to have all the information and buyers were at their mercy. The internet changed all that. Be an active listener. Help the prospect to get to the root cause of the problems they are trying to solve. With luck, you've got the solution. If you don't, be honest about it.

Less is more

Too much choice is a bad thing. In 1997 Apple offered 12 models of Macintosh. On his return, Steve Jobs narrowed it to four models and two choices: consumer or professional; desktop or laptop.

Mimicry works

Use the prospect's own language. This may be the only truism about selling that's backed up by research. If you're uncomfortable doing it on purpose, don't worry; you're probably doing it without thinking about it.

Be respectful of people's time

Everyone is busier than ever. If you want people to give you their time, make it worth their while.

Running Intel binaries in Debian ARM with Rosetta

Andrew Owen — Thu, 12 Jan 2023 08:29:16 +0000

I've mentioned UTM before. It's a nice wrapper for QEMU that enables you to create ARM virtual machines and emulate non-ARM machines on macOS. It's a free download from the website, or you can get it in the app store. But one of the features I've been looking forward to is being able to use Rosetta to do X64 to ARM64 instruction translation, which is supported in the latest version of UTM on macOS Ventura. I was hoping to be able to install Intel VMs using Rosetta, but for that you still have to use QEMU. What you can do is install a Debian ARM VM, enable Rosetta, and then run X64 Debian packages on that VM. This can be useful if there's a particular package you need that doesn't have a native ARM build. Thus far I've only got it to run packages, and not individual Intel binaries. There is also a big caveat:

I'm running on an M1 Pro, and that seems to work well. After you've installed UTM you'll need the Debian Net Installer. You'll also need to install Rosetta.

Set up the VM

Open UTM and click Add ( ➕ ) to open the VM creation wizard.
On the Start panel, click Virtualize, then on the Operating System panel, click Linux.
On the Linux panel, select Use Apple Virtualization, then select Enable Rosetta (x86_64 Emulation).
Click Browse and select the Debian installer ISO you downloaded earlier, then click Next.
Choose the amount of RAM and CPU cores you want the VM to use, then click Next. I used the default settings.
Set the maximum drive space to allocate, then click Next. I left this at the default 64GB. The image won't take up the full amount when you create it, and can be trimmed if you have sufficient disk space for a copy, so you should set this to the maximum amount you think you'll need.
(Optional) Choose a shared folder to mount in the VM, then click Next. If you skip this step, you can select the folder later from the VM toolbar.
Click Save to create the VM and then click Run ( ▶️ ) to start the VM.

Install Debian

When the VM boots, select Install and follow the setup wizard.
When formatting the disk, install to Virtual disk 1 (vda), using entire disk, all files in one partition
From Software selection, select GNOME, SSH server and standard system utilities.
After installation, eject the disk and reboot.

Enable sudo

$ set USERNAME=`whoami`
$ su -p
# /usr/sbin/usermod -aG sudo $USERNAME

After you enable sudo for the default user, you must restart the VM for the change to take effect.

Install the software

Install the guest tools: sudo apt install spice-vdagent.
Install binary format support: sudo apt install binfmt-support.
Create a mount point: sudo mkdir /media/rosetta.
Mount Rosetta: sudo mount -t virtiofs rosetta /media/rosetta.
Add this line to /etc/fstab: rosetta /media/rosetta virtiofs ro,nofail 0 0.
Register Rosetta as an X64 ELF handler:

sudo / usr / sbin / update - binfmts--install rosetta / media / rosetta / rosetta \
--magic "\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00" \
--mask "\xff\xff\xff\xff\xff\xfe\xfe\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff" \
--credentials yes--preserve no--fix - binary yes

The magic parameter describes the first 20 bytes of the ELF header for X64 binaries. The Linux kernel performs a bitwise logical AND with the first 20 bytes of any binary you try to run with the mask value. If there's a match, it uses the registered handler to interpret the binary. Otherwise, it reports an error.

7. Enable X64 packages:

sudo dpkg --add-architecture amd64
sudo apt update

Now you can now install and run any X64 package in the Debian repository with sudo apt install packagename:amd64.

Install WINE

One such package is WINE, which will enable you to run some 64-bit Windows binaries. But you'll also need to install WINE32 to get it to launch. I'm not sure if Rosetta can be persuaded to run 32-bit binaries as well. I'll have to do some further investigation. You'll also need to enable X86 pakcages:

sudo dpkg --add-architecture i386
sudo apt update

Then you can install WINE with:

sudo apt install wine64:amd64
sudo apt install wine32:i386

So far, I've only got the built-in file explorer working (launch with wine64 explorer). If I get 32-bit apps working I'll write a new post on it.

How to offend most of your international users all at once

Andrew Owen — Mon, 19 Dec 2022 18:49:50 +0000

We love icons. They're a great way to convey information simply, even if many of them are skeuomorphs from a bygone age. You know, like using a floppy disk ( 💾 ) to mean save; a telephone receiver ( 📞 ) for voice calls; an envelope ( ✉️ ) for email; a single lens reflex camera ( 📷 ) for taking a picture; a movie camera ( 🎥 ) for video; a folder ( 📁 ) for file containers; a calendar ( 📅 ) for dates; a newspaper ( 📰 ) for news feeds; a spiral notepad ( 🗒️ ) for text editors; an alarm clock ( ⏰ ) for alerts; a stopwatch ( ⏱️ ) for timers; a bed ( 🛏️ ) for sleep; a book ( 📖 ) for electronic publications; and so on. And I took most of those examples from the current version of iOS nearly a decade after Apple supposedly abandoned skeuomorphism. But we keep on using them because they are unambiguous, with a one-to-one meaning. Unlike say, flags.

Flags are problematic. All of them, not just the ones banned in Forza as “notorious iconography”. Typically, they represent a cultural identity that even those who reside within the state that they represent may not be comfortable with. They can also be unnecessary reminders of past wars, territorial disputes and current conflicts. And unlike icons, there is no one-to-one match between flags and languages. The same language may be spoken in multiple states. It is common for states to have at least two widely spoken languages. There are multiple states that use the same language. Some states have flags that look very similar to the flag of other states. And that's just scratching the surface of the problem.

The W3C has this to say about it:

And that misses the point that Ireland typically gets lumped in with the UK due to the shared use of English (at time of writing, www.amazon.ie redirects to www.amazon.co.uk). So what's the solution? Use the ISO two-letter language codes. And, optionally, you can include a hover text with the name of the language in that language. For example, FR [Français]. If you need to distinguish between variants of the same language, you can use the subtags from the IETF language tags. For example, PT-BR [português brasileiro]. If you're convinced, you could stop reading now. If not, here are some example problems.

Brazil 🇧🇷

Commonly used to represent Portuguese. There are over 100 Amerindian languages spoken in Brazil. There are also differences between Brazilian Portuguese and the Portuguese used in Portugal.

Chad 🇹🇩

Indistinguishable from the flag of Romania. The two official languages are French and Arabic. Setting aside using the flag of France for French, which flag are you going to choose for Arabic that isn't going to upset the occupants of at least one other Arabic-speaking nation?

France 🇫🇷

Commonly used to represent French. France has many regional languages, including Basque, Breton, Catalan and Corsican. French is one of the main languages in countries including Belgium and Switzerland. French is also a major language in many former French colonies that aren't too happy about having been colonized by France.

Germany 🇩🇪

Commonly used to represent German. Germany has many regional languages, including, Low Rhenish, North Frisian and Saterland Frisian. German is also the main language in Austria and one of the main languages in Switzerland.

India 🇮🇳

The main two languages are Hindi and English. But there are hundreds of languages in use. At time of writing, the constitution mentions 22 languages, with demands to add another 38.

Mexico 🇲🇽

Commonly used to represent Spanish. The federal government recognizes over 50 linguistic groups and over 300 varieties of indigenous languages. Spanish is spoken throughout South America, but there is no homogenous Latin American dialect. There are at least 16 languages besides Spanish and Portuguese used in South America with at least 125,000 speakers. Spanish as spoken in the Americas differs from that spoken in Spain. Spain itself has many regional languages, including Basque, Catalan and Galician.

United Kingdom 🇬🇧

Commonly used to represent English. English is an official language in over 50 states, although that doesn't include the United Kingdom, the United States, Australia or New Zealand. At the time of writing, the only official language in the UK is Welsh, and the only official flags are the Welsh and Scots flags. As I've mentioned before in other posts, there are two distinct spelling systems (Cambridge; -ise endings, and Oxford; -ize endings). Cambridge is used in most of the former colonies, except Canada (which has its own versions of English and French). The IETF advocates using the two-letter country code in addition to the ISO two-letter language code, but that produces EN-GB, which doesn't tell you if you're using Cambridge or Oxford. Also, much to the annoyance of the English, American is the most commonly used English dialect. I therefore propose the following codes:

(American) English: EN (the lingua franca, to the annoyance of the French)
Australian English: EN-AU (the official Australian version)
Cambridge English: EN-IE (same as Hiberno-English, an official language of Ireland)
Canadian English: EN-CA (any version of English that doesn't closely follow a single dialect)
New Zealand English: EN-NZ (vowel-reduced English)
Oxford English: EN-OX (English for classics scholars)
South African English: EN-ZA (English where vowels are entirely optional)
Strine: EN-OZ (the version of Australian English as it's actually used)

Image: The Esperanto flag, in case you were wondering.

Converting images with Image Magick

Andrew Owen — Mon, 19 Dec 2022 18:22:01 +0000

Photoshop is old. Really old. Well, in computer terms anyway. As of writing, it's currently on version 24.0. It was originally developed for the Mac in 1987 by Thomas Knoll, a PhD student at the University of Michigan, and his brother John, who worked for Industrial Light & Magic. Photoshop is a raster graphic (pixel image) editor. And because of its age, it has features for rendering 24-bit images (16 million colors) down to limited palettes, (which were a common feature of computers in the 1980s), that are missing from, or hard to use in, other image manipulation programs.

Another piece of software dating from 1987 is Image Magick. It was created by John Cristy at DuPont to convert 24-bit images to 8-bit images (256 colors). In 1990 Adobe became the publisher of Photoshop, and DuPont assigned the copyright in its tool to ImageMagick Studios LLC, a non-profit organization “dedicated to making software imaging solutions freely available”. So, if you can't afford over $200 a year for a Creative Cloud subscription just to convert 24-bit images to low color images, Image Magick is the obvious solution.

Some hardware that definitely doesn't date from 1987, but is designed as if it did, is the Chloe 280SE (the retro computer project that I will talk endlessly about if given the opportunity). The project is still in development, and at present its highest resolution graphics mode is incredibly complicated. It has a non-linear bitmap of 256×192 pixels. This is overlaid with a non-linear attribute map of 32×192 cells (each 8×1 pixels in size) that determine the foreground and background color. Each 8 pixel cell is rendered by paring a bitmap byte with an attribute byte. The attribute byte is divided into three parts. The highest two bits select one of four color look up tables (CLUTs). The middle three bits set one of 8 background colors, and the lowest three bits set one of 8 foreground colors. Background and foreground colors are defined independently. This gives 16 colors per CLUT, for a maximum of 64 colors on screen. However, it is not possible to combine colors from different CLUTs. The colors are chosen from a fixed palette of 256 colors based on half the 9-bit RGB palette (3-bits are used for red and green, but only two for blue). These are stored in GRB (MSB) order. A complete image consists of a 6K bitmap, 6K attribute map and 64 byte palette.

I said it was complicated. Fortunately, Edward Cree wrote an image conversion tool for Linux (scrplus) and Klaus Jahn made a Windows version (Image2ULAplus). These can both be used on a Mac with a suitable virtualization solution. However, the results can vary widely. This is the pre-conversion process if you have access to any version of Photoshop.

Scale the image you want to convert to 256×192 pixels.
Pattern dither the image to a uniform 128 colors.

Typically, Floyd-Steinberg or diffusion dither will give better results than pattern dither when reducing color depth. However, pattern dither seems to be the best method to reduce the visibility of the attribute cells. The palette has 8 levels for red and green, but only 4 for blue. Reducing the range to a uniform 128 colors translates to giving each color 5 levels in the input image. I don't know why, but that seems to give the best conversion results.

The conversion process after opening the input image in Image2ULAplus is:

Switch off:
- Reduce colors to 8-bit.
- Use dithering
- Create HAM256 screen
- Stretch to SCREEN$ size.
Switch on:
- Calculate palette
- CLUTs: 0, 1, 2, 3
- Create Timex screen
Set maximum colors to 64.
Click Render.
Save the image in .SCR format.

I've got a licensed copy of Photoshop CS6 on a 2010 MacBook Air. But I don't really want to have to get that out of storage every time I need to convert an image. So here's how to use Image Magick instead. First, you have to install it (unless it's pre-installed in your Linux distro): On Ubuntu, you'd use sudo apt install imagemagick and invoke it with the convert command. On macOS, the easiest way to install it is using Homebrew with brew install imagemagick. On Windows, you can download an executable.

With experimentation, I've found that the best setting for conversion to the Chloe 280SE is: magick input.jpg -resize 256x192 -ordered-dither o8x8,5,5,4 output.gif. This scales the image to 256×192 and then performs an ordered (pattern) dither on the image using an 8×8 pattern (which works well with 8×1 attributes). It applies a uniform palette with 5 levels of red and green, and 4 levels of blue (128 uniform colors in Photoshop gives approximately 5 levels for each color). The results vary, but for the test image that I've used in all my tutorials, Image Magick actually does a better job than Photoshop.

Now that's just one use case. Back in my days as a tech writer, I mainly used it for making .PNG images as small as possible for inclusion in online help files. And that's barely scratching the surface of what's possible with Image Magick. Fortunately, there's good documentation and an active community.

Using GitHub Actions to automatically unpack a zip archive

Andrew Owen — Mon, 19 Dec 2022 18:19:37 +0000

I was recently working with some software that could push a zip archive of content to a Git repository. However, what I really wanted was for the contents of the archive to be pushed to the repository. So I created a GitHub Action to do that for me. I've covered the format of GitHub Actions before. But to recap:

name is what gets displayed in the actions list.
on sets the triggers:
- push and pull trigger the script on push and pull requests. If you don't specify branches, they default to main.
- paths specifies the paths to match. In this case, the script will trigger when a zip file is pushed.
- worklflow_dispatch enables you to manually trigger the script from the actions list.
jobs defines one or more named tasks, in this example unzip.
runs-on specifies the VM environment. If you can use Ubuntu, it's the cheapest option with hosted runners.
steps can be used to invoke actions such as checkout (which fetches a copy of the repository to the VM) and to execute shell commands with name: run.
run with a pipe character ( | ) executes a multi-line script. Without it, a single line is executed.

And here's the action I created:

name: extract a zip file

    on:
      push:
        paths:
        - '**.zip'
      workflow_dispatch:

    jobs:
      unzip:
        runs-on: ubuntu-latest

        steps:
          - uses: actions/checkout@v2

          - name:
            run: |
              rm -r css
              rm -r en
              rm -r fonts
              rm -r js
              filename=$(basename -s .zip *.zip)
              unzip *.zip
              rm *.zip
              mv $filename temp
              mv temp/out/* .
              rm -r temp
              git config user.name github-actions
              git config user.email github-actions@github.com
              git add .
              git commit -m "unzip"
              git push origin main

The script is written for the Linux command line. Let's break it down.

rm -r css

    rm -r en
    rm -r fonts
    rm -r js

The idea here is that the contents of the zip file should replace what is already in that particular branch of the repository. You might want to call the branch uploads. The checkout action has already been run, but it's a good idea to clear out any known folders. The -r tag makes the action recursive.

filename=$(basename -s .zip *.zip)

    unzip *.zip
    rm .zip
    mv $filename temp

This script assumes that we don't know the name of the zip file, but that there is only one file. It will determine the name, unzip the file to the root, remove the zip file and rename the folder containing the zip to temp.

mv temp/out/ .

    rm -r temp

In this example, the contents of the zip file are two folders deep (in the out folder). This moves the contents from the nested folder to the root, and then removes the temp folder and its contents (the empty out folder). The dot (.) represents the current working directory (where the repo was checked out on the VM).

git config user.name github-actions

    git config user.email github-actions@github.com
    git add .
    git commit -m "unzip"
    git push origin main

This part of the script pushes the changes back to the repository.

Image: Detail from The Unarchiver zip file icon. I looked for an appropriate unzip image with a Creative Commons license, but the results were not safe for work.

Getting started in developer relations

Andrew Owen — Mon, 19 Dec 2022 18:17:42 +0000

It may surprise you that the field of developer relations has been around for nearly 40 years at the time of writing. It started at Apple with Mike Boich and Guy Kawasaki on the Macintosh project. But it didn't go mainstream until nearly 30 years later.

Apple had helped to define the personal computer market with the Apple II. Its killer app was VisiCalc, the first microcomputer spreadsheet. IBM watched as businesses rapidly adopted the Apple II, and its response in 1981 was the IBM PC. By the time the Mac launched in 1984, the IBM PC accounted for around 80 per cent of the PC market.

The Macintosh wasn't compatible with software written for the Apple II or the IBM PC, and if it was going to be a success, it needed software. So the role of software evangelist was created at Apple to promote the Mac as a development platform. And it worked, because unlike other IBM PC alternatives that launched in the 1980s, the Mac is still around.

In this age of disruption, it's widely recognized that if you want to get developers to use your products, what you need to offer them is the fastest route to developer success. The once popular Atari ST and Commodore Amiga are now remembered mainly as games machines, if they are remembered at all. You don't want your product to go the same way.

When I was getting started as a developer advocate, I reached out to someone I'd met at an API conference for advice. They gave me three things they wished they'd heard when they were starting out:

Recognize that you're wearing, at minimum, two hats. Your developer hat, which should feel familiar-ish, because now you're not just a developer. You're also in Product/Marketing/Engineering/Sales, whichever org DevRel sits within at your company. When you accept that you have multiple roles, it will be easier to prioritize the different goals.
Protect your developer time. People will want a lot more face time with you. You can give them face time, up to a limit. If all your time goes towards stakeholder meetings with other Product Managers, you will not be writing code. You need to keep writing some code, to maintain your credibility.
Your manager should be actively on your side. If not, tell them that's what you need from them for you to do your job successfully. A supportive manager is very helpful overall, I will personally attest.

He also recommended Mary Thengvall's book “The Business Value of Developer Relations”. And she recommends Jono Bacon's “The Art of Community”. The former is also a great read if you're planning to set up a DevRel department. The latter should be required reading for all community managers.

And now here's a list of sites that I've personally found useful in my role as a developer advocate: