michaelheap.com

Presentations on an ultrawide monitor

2024-05-13T09:17:51Z

I love having an ultra wide monitor, but it does make presenting tricky at times. All of the available conferencing systems allow you to share either a single window, or all of your screen. For most people, sharing a single window which is the right size works.

For me, it doesn’t. Most of the time I’m switching between a code editor, web browser and terminal. I need a way to share a 1080p section of my screen, no matter which window it’s showing.

Here are the two options I use:

Use Zoom to share a specific area of the screen + Hammerspoon to position the windows
Use DeskPad + any other conferencing tool

Zoom and Hammerspoon

This is the approach I use 99% of the time. It fits my existing workflow with a single display and allows me to drag things in to view as needed (or rather, use the Hammerspoon shortcut below).

This approach consists of two sections. The first is to position the window where it needs to be using Hammerspoon. I have a keyboard binding for this:

lua
function setWindowPosition(key, w,h,x,y)
  hs.hotkey.bind({"cmd", "alt", "ctrl", "shift"}, key, function()
    local win = hs.window.focusedWindow()
    local cursize = win:size()
    cursize.w = w
    cursize.h = h
    local f = win:frame()
    f.x = x
    f.y = y
    win:setFrame(f)
    win:setSize(cursize)
  end)
end
setWindowPosition("P", 1920, 1080, 2420, 285) -- Right

2420, 285 places the window 2420px from the left, and 285px down from the top of my screen. This is just below where my camera is mounted, allowing me to see the window and also look at the camera.

The second trick is to use Zoom’s “Portion of screen” option and select the area of the screen that your window covers.

At this point the core problem is solved, but there’s one remaining thing that frustrated me. The app switcher shows when I cmd+tab, but some icons are cut off as I’m only sharing part of the screen.

To solve this, I bind specific windows to a keyboard shortcut with Hammerspoon and switch using the keyboard. This prevents the app switcher from showing on screen.

I use cmd+alt+ctrl+shift+y to bind the focused window to y, and cmd+alt+ctrl+y to switch to it instantly. I have six hotkeys bound, which provides plenty of windows if I need them.

lua
function windowSwitch(binder)
  local windowId = 0;
  hs.hotkey.bind({"cmd", "alt", "ctrl", "shift" }, binder, function()
    windowId = hs.window.focusedWindow():id();
  end)
  hs.hotkey.bind({"cmd", "alt", "ctrl"}, binder, function()
    hs.window.find(windowId):focus();
  end)
end
windowSwitch("y")
windowSwitch("u")
windowSwitch("i")
windowSwitch("h")
windowSwitch("j")
windowSwitch("k")

DeskPad

Not all conferencing systems allow you to share a portion of your screen like Zoom. If I’m presenting through an app that doesn’t allow you to share a specific area and I need to show multiple windows, I use DeskPad.

DeskPad adds a virtual screen to your Mac, and an app that shows what’s on that screen. This allows you to share your entire “screen” whilst still keeping the majority of your ultra wide available for other things.

I configure DeskPad’s screen to be above my usual screen to make it easy to drag windows on to it.

If you’re feeling really fancy, you can combine DeskPad and Hammerspoon to move windows to DeskPad with a keyboard shortcut:

lua
hs.hotkey.bind({"cmd", "alt", "ctrl" }, ".", function()
  hs.window.focusedWindow():moveToScreen('Deskpad'):maximize()
end)

The End

If you're using Zoom, I can highly recommend the first approach. I use it daily and it hasn't failed me yet. If you're using a conferencing platform that doesn't allow you to share a portion of your screen, DeskPad is a great tool that lets you share a virtual screen at the resolution you desire.

Kong Gateway Quickstart

2024-05-07T08:34:54Z

A $dayjob related TIL today. Here's how to quickly deploy Kong Gateway locally with the Dev Portal enabled (you'll need an enterprise license).

This is useful for testing things locally.

Run the Gateway:

bash
curl -Ls https://get.konghq.com/quickstart | PROXY_PORT=80 bash -s -- -m \
    -e KONG_PASSWORD=changeme \
    -e KONG_ADMIN_GUI_URL=http://manager.example \
    -e KONG_ADMIN_GUI_API_URL=http://admin.example \
    -e KONG_PORTAL_GUI_PROTOCOL=http \
    -e KONG_PORTAL_API_URL=http://portalapi.example \
    -e KONG_PORTAL_GUI_HOST=portal.example \
    -e KONG_PORTAL_SESSION_CONF='{"cookie_name": "portal_session", "secret": "PORTAL_SUPER_SECRET", "storage": "kong", "cookie_secure": false, "cookie_domain":".example"}'
    -e KONG_PORTAL="on" \
    -e KONG_LICENSE_DATA \
    -t 3.4

Create routes that proxy based on host name:

bash
curl -X POST localhost:8001/services -d name=admin -d url=http://localhost:8001
curl -X POST localhost:8001/services -d name=manager -d url=http://localhost:8002
curl -X POST localhost:8001/services -d name=portal -d url=http://localhost:8003
curl -X POST localhost:8001/services -d name=portalapi -d url=http://localhost:8004
curl -X POST localhost:8001/services/admin/routes -d hosts=admin.example
curl -X POST localhost:8001/services/manager/routes -d hosts=manager.example
curl -X POST localhost:8001/services/portal/routes -d hosts=portal.example
curl -X POST localhost:8001/services/portalapi/routes -d hosts=portalapi.example

Add those domains to your /etc/hosts file:

bash
echo '
127.0.0.1   proxy.example
127.0.0.1   admin.example
127.0.0.1   manager.example
127.0.0.1   portal.example
127.0.0.1   portalapi.example
' | sudo tee -a /etc/hosts

Now you can visit http://manager.example and log in with kong_admin / changeme.

Designing OpenAPI Schemas

2024-04-27T19:36:48Z

I’ve written a lot of OpenAPI schemas over the last couple of years, and have developed a pattern that helps with maintenance. You have a minimum of two logical schemas for every entity in your system, Foo and FooRequest . Foo is a union of FooRequest and any computed fields from the system.

Let’s look as a concrete example, a Pet in an adoption shelter. A pet has two user set fields, name and type, and one computed field, created_at. You can’t set the created_at field when creating or updating a pet, which means we have two schemas:

PetRequest : name, type
Pet: name, type, created_at

The following example isn't the best way to accomplish the GET/POST split! It's shown as it's a common pattern used in many specifications, but keep reading for a better solution.

When you model this with JSON schema, it looks like the following:

yaml
components:
  schemas:
    PetRequest:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
    Pet:
      allOf:
        - $ref: "#/components/schemas/PetRequest"
        - type: object
          properties:
            created_at:
              type: string

Any updates to the PetRequest object will automatically be reflected in the Pet object. However, this is such a common pattern that OpenAPI has keywords to help built in.

Simplify with `readOnly: true`

If you can split your schema in to "user provided" and "computed" values cleanly, you only need a single schema thanks to the readOnly keyword.

yaml
components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        created_at:
          type: string
          readOnly: true

The readOnly keyword causes the schema to be split in to two virtual schemas - one for GET and one for POST/PATCH/PUT. Any OpenAPI renderer (I tested with Redoc) will remove created_at from the POST schema.

Complex APIs

In an ideal world, you wouldn’t need more than one single Pet schema. However, we live in the real world and sometimes there are additional requirements. Here are some examples:

Pets have an adopted_at time, which can only be set when updating a pet, not when creating
Pets have a total_steps field which is computed from an external source that is not cached and is too expensive to show when listing multiple pets

These requirements mean that we have to split Pet in to two, Pet and CreatePetRequest. We also need a MinimalPet representation for the GET /pets endpoint. This results in three distinct schemas:

CreatePetRequest: name, type
Pet: name, type, adopted_at (readOnly), created_at (readOnly)
PetWithDetails: name, type, adopted_at (readOnly), total_steps (readOnly), created_at (readOnly)

These schemas can be composed to build the entities we need at runtime. CreatePetRequest is the base as it contains the minimum available information. Pet builds on this by adding adopted_at and created_at. Finally, PetWithDetails adds computed fields that are expensive to calculate such as total_steps.

CreatePetRequest -> Pet -> PetWithDetails.

Expressed using JSON schema, it looks like this:

yaml
components:
  schemas:
    CreatePetRequest:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
    Pet:
      allOf:
        - $ref: "#/components/schemas/CreatePetRequest"
        - type: object
          properties:
            adopted_at:
              type: string
            created_at:
              type: string
              readOnly: true
    PetWithDetails:
      allOf:
        - $ref: "#/components/schemas/Pet"
        - type: object
          properties:
            total_steps:
              type: string
              readOnly: true

This gets expanded to the following schemas (courtesy of Swagger UI):

Here's a complete OpenAPI specification that uses these schemas.

An ideal world

Although the model works for APIs that have complex requirements, I consider needing separate models for create and update requests a design flaw. In this example API, you could make adopted_at a nullable field and use the same schema for both create and update requests.

I also consider needing a minimal representation of an entity a design flaw.There are cases where there is a real requirement that needs these schemas (e.g. if total_steps must always be accurate and can’t be cached) but these cases are rare.

If you find yourself using more than one schema, take a moment to reconsider your API design and see how you can simplify it.

Workspace layouts with Hammerspoon Grid

2024-01-10T15:10:39Z

Since I switched from Arch to MacOS there’s been an i3 shaped hole in my life. I’ve used apps like Divvy to approximate it, but it’s not the same.

I tried out some of the MacOS tiling window managers, but couldn’t get to grips with them. Between having to trigger things using external apps (Yabai and skhd) and having to disable system integrity protection, things just didn’t click. One of the things I loved about i3 was its simplicity.

After many years of searching, I think I’ve found a solution in Hammerspoon.

Hammerspoon?

Hammerspoon is an automation framework for MacOS that allows you to script various things using Lua.

I’ve written about Hammerspoon before, and have been using it for window management since I abandoned Divvy a couple of years ago (when I configured a dedicated hyper key on my keyboard).

I was recently browsing through Jakub’s Hammerspoon config and spotted his usage of hs.grid to configure predefined layouts.

Predefined layouts were one of my big use cases for i3, and so I went digging.

hs.grid

hs.grid splits your screen into an x by y grid. You can place windows by specifying a width/height along with an offset for the x and y values.

I have split my screen in to an 8x2 grid, with zero margin. I also have a shortcut to show the grid overlay on screen in case I want to position a single window in a non-standard layout.

lua
hs.grid.setMargins(hs.geometry.size(0,0))
hs.grid.setGrid('8x2')
hs.hotkey.bind(hyper,'g',function()
  hs.grid.show()
end)

To align a window to the grid, you call hs.grid.set and pass an instance of hs.window as the first parameter. The window is being placed on the right hand side of the screen (4 cells offset on the x-axis, 0 on the y-axis, and it covers a 4x2 space on an 8x2 grid).

lua
hs.grid.set(window, '4,0 4x2')

Automatic layouts

One of the things that I loved about Jakub’s Hammerspoon config is that he had a helper function to discover all of the windows for a certain app before reflowing windows in to the grid.

I borrowed this idea and built some convenience functions which allow you to define layouts like this:

lua
defineLayout("Writing", 1, {
	{'Bear', '0,0 2x2'},
	{'Arc', '2,0 4x2', true}
});
defineLayout("Code", 2, {
	{'Arc', '0,0 2x2'},
	{'Code - Insiders', '2,0 4x2', true},
	{'iTerm', '6,0 2x2'}
})

Now I can press hyper+1 to have Bear on the left 1/4 of the screen and Arc in the middle half. If I’m writing code, I can press hyper+2 to have VSCode in the middle taking up half of the screen, with Arc on the left and a terminal on the right.

Applications will only be positioned if they are already launched. Hammerspoon provides a hs.application.launchOrFocus() method, but I chose to implement focusIfLaunched as sometimes I don’t have all the apps open (e.g. Bear is optional when I’m writing).

Give it a go

Hammerspoon is wonderful, and I recommend giving it a go if you haven’t already tried it. My Hammerspoon config is publicly available, and whilst I’m not a power user, it saves me a ton of time every single day.

If you’ve a Hammerspoon user and have tips and tricks you want to share, I’m @mheap@hachyderm.io. I’d love to hear them!

Bonus content

I’ve recently stumbled across aerospace, which bills itself as “an i3-like tiling window manager for macOS”. I haven’t given it a go yet, but it looks promising based on the YouTube video.

Could/Should/Will/Why

2024-01-08T20:27:59Z

I had an interesting conversation with my manager this week. I’ve been working on a lot of different projects, and was a little spread thin. In one of our calls my manager asked me why I’m working on .

We sat and chatted about it, and I tried to answer the question: why am I doing these things? After hearing me out, they agreed that everything I was doing was important. Then they repeated the question, with a slightly different emphasis:

Why am I doing these things?

I didn't have a good answer. The things needed doing. No-one else was doing them. I could do them, so I took them on. But why was I the one taking them on?

A day has a finite number of hours. If I’m spending my time doing X, then Y isn’t getting done. If Y is something that only I can (or will) do, then isn’t that a better use of my time than X?

Here’s a concrete example. I had a choice to either:

Write some tutorials for one of our products using the API
Build a proof of concept Terraform provider to understand if we want to invest in the next financial year

My decision? To do both. Work on the proof of concept first, and write some tutorials between my meetings once it's done.

That’s the wrong answer.

It turns out that writing tutorials isn’t my responsibility. More than that, by writing them I’m taking away learning opportunities from others. I’m taking it away from the product manager that wants to learn to write documentation. I’m taking it away from the writer that wants to learn more about API development.

Anything I take on should meet one of the following criteria:

No-one else can do the work
It’s time sensitive, and no-one else has capacity
There’s a learning opportunity for me

Building a system

When my manager asked why I was working on these projects, I realised that I couldn’t answer. We talked about who could do the work, who should do the work, and who will do the work. This gave me a good framework for evaluating projects before starting them.

I’ve added a final column - why - to help keep a record of why the person that will take on the project is responsible.

Here’s an example with a couple of projects:

Project	Could	Should	Will	Why
Public Demos	DevRel, Sales Engineering	Sales Engineering	Sales Engineering	Demos are a core part of the SE role. If DevRel build demos, there would be duplication.
Release Demos	Product, DevRel, Product Marketing	Product Marketing	DevRel	DevRel has an engineering background to understand the features + how to get started
Splunk Tutorial	Docs, DevRel	Docs	DevRel	Docs team is at capacity with regular release documentation
VSCode Extension	DevRel, Engineering	Engineering	N/A	Project not prioritised.
Terraform Provider	DevRel, Engineering	DevRel	DevRel	This is an initial proof of concept exploration. If the idea shows potential, it's added to the Engineering roadmap.

Let’s work through the tutorials example in more detail:

A community member asked how to send logs from Kong on a VM to Splunk
DevRel couldn’t find any existing documentation to send them
DevRel the docs team if they could write a new tutorial
The docs team share that they’re already overcommitted.

At this point DevRel have three choices:

Abandon the project
Submit it in to the docs team backlog
Do it themselves

This is your classic prioritisation problem. Whichever option you choose, fill out the why column with the rationale then move on.

Has it helped?

Kind of. I still take on more projects than I should, but having an explicit will step forces me to think about why we’re taking on this specific project. It forces me to talk to other people about the project. Could their teams take on the work? Do they want to take on the work? Are there learning opportunities?

Next time you have an idea for some work that needs doing, run it through could/should/will/why to make sure that you’re the best suited person or team to complete the project.

Create an AWS RDS database

2024-01-05T15:52:09Z

I've been using RDS to provide throwaway databases for testing and wanted to work from the CLI to speed things up. The aws rds incantations were hard to find at times, so here they are for posterity.

Create a publicly accessible Postgres database:

bash
aws rds create-db-instance --db-instance-identifier demo-db --db-instance-class db.t3.micro --allocated-storage 50 --engine postgres --publicly-accessible --master-username postgres --master-user-password YOUR_PASSWORD

Show the database status and connection details:

bash
aws rds describe-db-instances | jq '.DBInstances[] | select(.DBInstanceIdentifier == "demo-db") | .DBInstanceStatus,.Endpoint'

Delete the database:

bash
aws rds delete-db-instance --db-instance-identifier demo-db --skip-final-snapshot

Create an Azure AKS Cluster

2024-01-05T15:50:50Z

I needed to test Azure AKS with the Application Gateway Ingress Controller. Thankfully, Azure makes it easy with it's az aks CLI.

Create a new Azure resource group:

bash
az group create --name mheap-test --location uksouth

Create a new AKS cluster with the Azure Application Gateway Ingress Controller enabled:

bash
az aks create --name mheap-aks-test --resource-group mheap-test --node-count 1 --network-plugin azure --enable-managed-identity --enable-addons ingress-appgw --appgw-name mheap-appgw --appgw-subnet-cidr "10.225.0.0/16" --generate-ssh-keys

Configure kubectl to connect to this cluster:

bash
az aks get-credentials --resource-group mheap-test --name mheap-aks-test

Once you've finished testing, delete the AKS cluster and resource group:

bash
az aks delete --name mheap-aks-test --resource-group mheap-test --yes
az group delete --name mheap-test --yes

Does this live in the docs or on the knowledge base?

2024-01-05T15:21:17Z

You may also be interested in my thoughts on content living on a blog vs docs

Making customers successful with a product requires three key components:

UX: If the application is intuitive, customers are successful without thinking about it.
Documentation: Practically speaking, most apps need supporting documentation to explain new concepts or provide concrete implementation instructions.
Support: Heroes that work directly with customers every day to make them successful in a 1:1 setting.

Great UX is the ideal solution, but in most companies, customers need supporting enablement content.

As the company grows, both the documentation and support teams build out their own libraries of content to make customers successful. Eventually, they’ll hit a critical mass and someone asks the inevitable question:

Does this live in the docs or on the knowledge base?

Both teams want their content to live in their own system. Support wants to use the knowledge base as it has deep integration with their ticketing system, with workflows for pulling answers from articles which aren’t always able to integrate with external docs. Docs want to use their docs-as-code platform and all the tooling that they’ve built around the written word.

Where does the content live?

Whatever you do, don't store the content in both places. The second copy goes out of sync before you even hit publish.

Instead, categorise content in two buckets:

This is generally applicable to the majority of customers using this product
This is specific to a small number of customer setups

Imagine that you have a customer issue come in and the support team resolves it. Now what? Where does the solution go?

If the answer applies to the majority of customers, then I recommend having a small KB article so that it shows up in their day to day workflow, but the KB article has a small description that then links to docs.

If the answer is specific to a small number of customers, the answer lives in the KB. The support team shares these answers on demand in response to tickets. They're also available if people search the KB specifically (or on the docs too if you have multi-site indexing).

Splitting content by audience allows you to keep your documentation focused on the 80% of customers that can be successful without human interaction. Providing an exhaustive list of failure modes makes it difficult for customers to find what they're looking for when everything is working as expected.

Examples

The above is quite abstract, so here are some examples from the docs teams that I’ve been a part of.

Vonage provides communication APIs, including SMS. Sending an SMS using the API is something that was applicable to everyone, so it had public docs. Restrictions around the sender ID (from) used are different on a per-country basis (Peru for example). Most of Vonage’s customers were in the USA where there were no restrictions, so this information lived in the knowledge base. When the USA introduced 10DLC it affected the majority of customers, so the restrictions were added to the public docs and the knowledge base.

Kong provides connectivity tools, such as API Gateways and Service Meshes. Older versions of Ubuntu don’t have a required library (zlib) installed by default and every customer using an old version of Ubuntu encounters this issue, so we document it on the installation page. Kong Mesh allows you to proxy requests to Redis, but sometimes you get a cryptic "Error: Protocol error, got "H" error. This means that you configured your MeshGatewayRoute as with a HTTP protocol rather than TCP. A small percentage of customers hit this issue, so it lives in the knowledge base.

TL;DR

If it’s applicable to > 50% of customers, put it in the public docs
If it applies to a small percentage of customers, put it in the knowledge base
Make the support team’s life easier by putting pointers to public docs in the knowledge base

Create an Amazon EKS Cluster

2023-12-20T16:44:58Z

I've been using this Terraform module to deploy test EKS clusters for the longest time, but I just learned that it's even easier when using eksctl.

Create a cluster.yaml file with the following contents. You can change the instanceType and desiredCapacity (the number of nodes) if needed:

yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: mheap-testing
  region: eu-west-2
nodeGroups:
  - name: ng-1
    instanceType: m5.large
    desiredCapacity: 1
    volumeSize: 80
    ssh:
      allow: false

Run eksctl create cluster. It takes around 4 minutes:

bash
eksctl create cluster -f cluster.yaml

Update your kubeconfig using the aws CLI:

bash
aws eks --region eu-west-2 update-kubeconfig --name mheap-testing

Now you can run all the kubectl commands that you want.

To delete the cluster when you're done:

bash
eksctl delete cluster -f cluster.yaml

How I work: Email

2023-09-09T11:06:19Z

Depending on who you ask, I’m excellent with email, or terrible with email. I don’t let it run my life, and process my (work) inbox every 2-3 days.

My review process has four steps: triage, unsubscribe, respond and prioritise.

Triage: Read all unread emails in my inbox with the search is:unread in:inbox.
If there are emails that I don’t want to receive (e.g. cold outreach) I create a filter based on the sender so that it doesn’t land in my inbox
Things that take 2 minutes to answer are responded to immediately. Otherwise they’re labelled (not starred - more on this later) for action later
Finally, I go through my labelled items and import them in to Sunsama to be scheduled alongside my other work.

The Klinger email method

I’ve been using a multiple inbox setup from Andreas Klinger for years. Having a main inbox, then separate inboxes for high/medium priority emails allowed me to keep on top of things that I needed to do.

Go and read the Klinger email method now

However, since I started using Sunsama my inbox is no longer the source of truth for what I need to do. Instead, it’s an input in to my Sunsama plan.

Pain Points

The Klinger method is great, but it isn’t perfect. I have two big complaints, and they both have to do with the use of custom stars.

The mobile gmail app only supports star/unstar, not custom stars
Sunsama only support starred/unstarred, which meant I lost my high/medium priority differentiation

To work around this issue, I created two labels: priority/high and priority/medium. I use these for my custom inboxes instead of the red and yellow bang stars from the Klinger method. This allows me to set priorities on mobile, and filter to specific priorities within Sunsama.

The real game changer for me was when I learned that you can customise label colours. Click on the three dots next to the label name in the sidebar and choose a label colour. I chose red for high priority and yellow for medium priority. The colours help these emails stand out when I’m scrolling through my inbox.

Sunsama Integration

Finally, it’s time to look at my Sunsama workflow for emails. I review emails tagged with priority/high or priority/medium on a Monday, Wednesday and Friday.

I start with priority/high and schedule work on those emails until the list is empty. Once there are no more remaining, I start working through priority/medium emails. When the email is imported in to Sunsama, the priority label is removed automatically which makes Sunsama the source of truth.

Email is one of my lowest priority task sources. I’ll always pull from Slack and GitHub before working through my email task backlog. However, everything that comes in via email does eventually need doing so pulling them in to Sunsama is important.

michaelheap.com

Presentations on an ultrawide monitor

Zoom and Hammerspoon

DeskPad

The End

Kong Gateway Quickstart

Designing OpenAPI Schemas

Simplify with readOnly: true

Complex APIs

An ideal world

Workspace layouts with Hammerspoon Grid

Hammerspoon?

hs.grid

Automatic layouts

Give it a go

Bonus content

Could/Should/Will/Why

Building a system

Has it helped?

Create an AWS RDS database

Create an Azure AKS Cluster

Does this live in the docs or on the knowledge base?

Where does the content live?

Examples

TL;DR

Create an Amazon EKS Cluster

How I work: Email

The Klinger email method

Pain Points

Sunsama Integration

Simplify with `readOnly: true`