How I built Jamaican by Descent

Jamaican by Descent started as a Google Doc I shared with friends and family. I turned it into a website so more people could use it. This page covers the problem it solves, the decisions behind it, and what the same ideas could do for the official process.

Where it started

A few years ago I claimed Jamaican citizenship by descent for a business venture in Jamaica, then applied for my first Jamaican passport through the High Commission in London. Once I had, friends and family wanted to do the same, so I wrote up everything I'd learned in a Google Doc.

The doc helped, but everyone still had to work out which parts applied to them. So I rebuilt it as a guided service.

The problem

Claiming citizenship by descent from the UK is a paper process, and there are plenty of ways to get held up:

• names that don't match across certificates: a different spelling, a different order, or a missing middle name
• bringing the short birth certificate, which isn't accepted
• Jamaican certificates that take weeks to order from overseas
• appointment slots that are hard to get
• a long wait for a decision, with few updates

Each of these can mean another trip, another order, or a delay of weeks.

From a Google Doc to a guided service

Documents

Google DocOne long list for everyone WebsiteOnly the documents for your route, whether you're claiming through a parent or a grandparent

Names

Google DocA warning to check your names carefully WebsiteA name check that compares every document as you type, explains each mismatch and how to fix it

Progress

Google DocRemember where you got to WebsiteStages that track your progress, with checklists you tick off as you go

Appointment day

Google DocRe-read the doc on the way there WebsiteA packing list for the day, as a PDF or in your calendar

Waiting

Google DocSet your own reminders WebsiteOptional email reminders to check for cancellations and to chase the High Commission

The decisions that mattered

Start with the step people get wrong

Mismatched names are the easiest way to have an application held up, and the hardest to spot by eye. The name check asks you to type each person's name exactly as it's printed on each document. It flags a missing name, a different order or a different spelling, then shows what to do and adds any extra documents you'll need.

Show each person only what applies to them

A short eligibility check and your route (parent or grandparent, mum's side or dad's side) decide which documents, examples and steps you see. Change an answer and the rest of the guide reshapes itself.

Familiar, accessible patterns

The forms follow the GOV.UK Design System's patterns: one question per page, clear labels and hints, and error messages that link to the problem. The look is its own, so nobody mistakes it for an official service. You can read the accessibility statement.

Private by design

There are no document uploads. You can use the guide without an account, and saving your progress only needs an email address, with no password. You can download or delete everything at any time.

Content anyone can keep up to date

Fees, links, documents and tips live in plain text files, separate from the code, with "last checked" dates on anything that changes. Keeping the guide accurate doesn't need a developer.

A small design system

Colours, type sizes and components are defined once and documented, so every screen stays consistent as the guide grows.

What this could mean for the official process

This guide is independent and sits outside the official process. But the same ideas could help applicants and the teams who process their applications:

• Checking names before an application is submitted could mean fewer applications held up by mismatches.
• Showing each applicant only the documents they need could mean fewer incomplete applications.
• Clear stages and realistic timelines could mean fewer "where's my application?" enquiries.
• Alerts for cancelled appointments could help fill slots that would otherwise go unused.

I'd be glad to share what I've learned with PICA, the Jamaican High Commission, or any team working on digital services for Jamaica and its diaspora.

How it's built

For the technically curious:

• Ruby on Rails 8, with Hotwire (Turbo and Stimulus) for the live name check and checklists
• SQLite on Fly.io, with personal details encrypted, continuous backups, and Solid Queue running the daily reminder emails
• GOV.UK Design System form patterns, restyled with a custom theme
• Passwordless sign-in by email link
• PDF and calendar downloads for appointment day
• Automated tests covering the eligibility, citizenship and passport journeys

Work with me

I design and build digital services that make complicated processes simple, from the first sketch to a working, accessible product. If you'd like something like this for your organisation, I'd like to hear from you.

Lisimba Gilkes