I signed the Hope Accord.
12 February 2024

Reporting and recording with plaintext and SvelteKit

Like many hackers, I like keeping records in plain text files. A couple of examples I’m maintaining at the moment are:

  • Time tracking for a software project. The format is something like:

    5/2
    
    0900-15 meeting
    15 ABC-1234 updating foo - 1000
    
    6/2
    
    1100 ABC-1234
  • Accounting for my jaw expansion treatment:

    02/05/23, esta, 17.01 + 0.50
    01/06/23, heathrow parking, 2700
    02, seat reservation, 3600
    ^, flights, 97501
    ^, Hampton hotel, 43608 + 1021

As you can see, the formats are lax and idiosyncratic – they’re a reflection of my own thought processes plus some ad-hoc shortcuts to make things easier to type in.

This makes them unsuitable for viewing by other people, which is where SvelteKit comes in.

SvelteKit

Instead of keeping these records inside an actual plaintext file, I keep them in a JavaScript template string inside a Svelte component inside a SvelteKit project. I use mdsvex along with Josh Collinsworth’s excellent SvelteKit + Markdown blog guide to get things like markdown support and automatic listing of pages: each file/report is a page/post.

The surrounding JavaScript, markup, and framework code transforms these ad-hoc records into whatever form I want to display them in. For work, I display the minute-by-minute records along with a summary for each day and an average for the reporting period. For the treatment costs, I break down everything by provider, trip, expense type, and so on. (The costs are integrated into my UK -> US Jaw Expansion Guide.)

This system lets you create and maintain your records as plain text—for your own viewing and editing, you can just open the .svelte or .md file—while also allowing you to quickly develop a custom reporting app around each file.

Advantages

There are several advantages to this ad-hoc way of developing reports:

  • You can do as much “software engineering” as you want. Pages can share libraries or be entirely self-contained. It doesn’t matter if each time report, for example, looks slightly different to the last. They’re one-off documents with only two users, you and the client.

  • Much of the programming and design required is easy and fun, because there are no heavy software engineering concerns to worry about. Code quality doesn’t matter (much). Your pages never have to talk to a database, an API, or anything else that changes. You don’t have to read the docs for the plaintext format because you invented it. If you change it for the next report and you don’t share code, the old reports still work exactly the same. Accessibility, usability, and branding are defined entirely by your preferences.

Code

See example repo: sveltekit-reports. This includes a bunch of stuff from the blog project it was cloned from, so could be stripped down further.