Danny Smith - Articles

Introducing Astro Editor

Thu, 08 Jan 2026 00:00:00 GMT

I’ve launched Astro Editor, a desktop app for authoring and editing Markdown and MDX content in local Astro Content Collections! I’m actually a bit late with this blog post since I shipped 1.0.0 six weeks ago, but hey – better late than never!

What is it?

Most Astro content collections basically comprise two things: a folder containing markdown files with their metadata as YAML frontmatter, and a Zod schema describing the structure that frontmatter should have. These content files live alongside your code.

Astro Editor provides an interface for working with these markdown files which is designed for writing not coding. The editor itself is a distractionless flow-state writing environment – it’s minimalist and gets out of your way. The frontmatter isn’t shown in the document, it appears as suitable UI components in a hideable sidebar. This shows both the frontmatter in the actual file and the available fields from the content collections schema. Here’s a screenshot of me writing this article right now.

When I dragged that screenshot into the editor it was automatically copied to the right folder in my project and renamed appropriately before the markdown image tag was inserted. I can check it’s the right one by holding ⌥ while hovering over the image tag, which shows a little preview. Astro Editor is full of little features like this, all of which are intended to let you focus on writing words without getting distracted. You can see the main features on the website (more in the userguide). Here’s a full explanation and demo:

Why?

Because I’ve wanted this myself for ages and the closest I ever got was Darkmatter – which I paid for and used regularly but never quite did what I wanted.

But why?

Most folks who publish content with Astro work in two distinct modes. We’re in coder mode when we’re editing Astro components, pages, CSS etc. This is best done in a coding tool like VSCode. We’re in writer mode when we’re writing or editing prose in markdown. Editors designed for coding are not well suited to this - they have too many distractions and lack the kinds of tools which help with writing and editing prose.

Because of this, it’s common for people to write in tools like iA Writer or Obsidian and then switch to VSCode to add frontmatter, build and publish. The workflow often looks something like this:

Create a new draft markdown file & start writing
Edit and tweak (maybe over a number of sessions)
Add frontmatter for things like description, tags etc
Build & run locally to check everything works
Push to github and deploy/publish

Steps 1-3 are very much writer mode tasks, while 4 & 5 are definitely coder mode tasks. Astro Editor is only concerned with the former which means things like:

Code blocks are not syntax highlighted because writing example code should be done in a code editor.
You can’t commit or publish because that’s best done in a code editor or terminal.
You can’t preview your writing because that’s best done in a browser while running your site on localhost.

And because the goal is simplicity when in writer mode, Astro Editor is intentionally opinionated about its UI and limits the user customisation features to “making it work with your Astro project and no more”. It’s not possible to customise colour schemes, typefaces etc.

Where we at now?

At time of writing 1.0.5 is stable for macOS and Windows and the GitHub repo has 328 stars. While I don’t collect analytics, I do get a ping whenever the auto-updater checks for a new version (which only happens automatically on launch). This includes only the currently installed version, the OS (mac or win) and a random UUID unique to each install. So I know that as of Thursday 8 January 2026:

There are 276 unique installs, 264 of which are on macOS and 12 on Windows.
Only 20 installs are pre-1.0.0
14 people opened Astro Editor today (probably, including me).

More importantly though… I’m writing in it basically every day. And I really fucking enjoy it.

So what’s Next?

Short answer: Finished Software. After years working in VC-funded startups which by definition can never be “finished”, it’s weirdly exciting to look at a 6-month-old Astro Editor and think “yeah I think it might be finished soon”.

I do still have one or two things on the roadmap though…

A complete reworking of how project config is managed, including some new options to control file naming.
Internationalization and basic RTL support.
Better quick search and internal link insertion.

And maybe better Linux support someday.

If you have an Astro site, please give Astro Editor a go. It’s only got to where it is now thanks to a bunch of folks trying it out and sharing feedback on GitHub.

And as a free open-source side project, the only marketing it’s gonna get is from people who like it saying so on their socials & websites. So tell your mates. Plz 🙏

Quite The Journey

I didn’t mean to build anything proper here. In July ‘25 I was just starting to properly experiment with AI coding beyond Copilot & Cursor autocomplete and was looking for a project to use as a guinea pig. My basic requirements were:

It can’t be throwaway because learning how to hold these new AI tools properly meant more than blind vibe coding.
It can’t be a toy for the same reason.
It must be something I’ll use daily if it works because otherwise I’d not have been invested in its quality.
It must have a GUI because at the time LLMs were turbo-shit at UI design, which made this a key learning goal.
Ideally, it’s designed to run locally because any non-toy web app involves a bunch of third-party services to handle auth and emails and file storage and all the rest. Some of which cost money and all of which require me – the human – to manage them.

So I settled on iA Writer but how I want it to write my blog, which ticked all the boxes. And duly dictated some nonsense requirements into a markdown file and had cursor turn it into what I thought would be a good PRD, which became Astro Editor’s first commit.

As an AI Coding noob the maybe-kinda-working app Cursor built from this felt like magic, but after a few hours going round in circles I actually read the code and realised it was (obviously) dogshit slop. And so began the very interesting process of working out how to do that better, which I’ll write about in another article.

Fast forward a few months and I had a completely rewritten Astro Editor with a not-so-insane architecture, which both me and my new friend Claude could reason about well enough to iterate on features quickly and reliably. And on 18 Aug I shipped a feature-complete 0.1.20 and shared in the Astro Discord! 🎉

Feature complete my arse.

Turns out not everyone has the same Astro setup as me. So I spent September-November dealing with that, which involved a completely different approach to schema reading/parsing, lots of testing on weird and wonderful Astro projects and a smattering of new features.

I released 1.0.0 on 22 November 2025.

Moving this site to Astro

Sat, 25 Oct 2025 00:00:00 GMT

I started on a redesign of this site <a href="/writing/website-redesign-i">back in May 2020</a> after deciding I wanted a simpler, content-first statically generated site. My main goals were to keep the core as simple as possible – writing in markdown and minimal boilerplate code – while allowing me to noodle around with new-fangled CSS & web-native stuff when I want to.

After about three years running on Jekyll I started to get frustrated at some of the stuff I couldn’t do easily - primarily the difficulty of working with custom components in markdown. I was using some kinda-janky markdown pre-parsers to let me insert things like callouts…

{:.callout}
This is a callout

Which wasn’t exactly easy to work with and more importantly, if I ever decided to switch away from Jekyll and export all my markdown files, wasn’t exactly obvious or intuitive.

What I really wanted was the ability to use HTML- or React-like components in my markdown. And as with web components or react components, I wanted to define these as self-contained components with scoped CSS and the like.

So in early 2023 I started playing with AstroJS. The most appealing thing about it was the native support for MDX, its React-like component architecture where .astro files contain scoped HTML, CSS and JS, and the relatively small amount of boilerplate needed to get a blog up-and-running.

I quietly ported this site over to Astro, but with the release of Astro 3.0 in August ‘23 so much had changed that it made more sense to start again from scratch. So I switched to the current codebase around the time Astro 4.0 dropped in December ‘23.

Why Astro?

Modern, Simple & Content-First

Astro is very well designed, and because it’s built with a modern TypeScript-based stack, it comes with all the advantages you’d expect (typesafe javascript among them).

When used as an SSG, Astro is also very simple. File-based routing, markdown parsing and YAML frontmatter Just Work™ and stuff like image optimisation come out-of-the-box. And while composing pages from astro components feels very Reactish, it’s “zero JavaScript by default” – the generated site will only include client-side JS when necessary, which for this site is hardly ever.

Astro has an extremely strong ecosystem of plugins, tools and themes around it.

Astro Components & MDX

Components can be anything from a tiny snippet of HTML to a reusable UI component (which takes props and/or content) to a whole page layout. Here’s an example.astro component:

---
const { title } = Astro.props;
const theNumber = Math.random();
---

<section class="mything">
  <h1>{title}</h1>
  <p>Number: {theNumber}</p>
</section>
<style>
  h1 {
    color: red;
  }
</style>
<script is:inline>
  alert('Hello');
</script>

The TypeScript in the component script at the top runs only at build time. The ability to co-locate this “server-side” code with the component is useful for keeping things organised.
The component template (below the last ---) is the HTML which will be rendered when the component is used, except (much like JSX) you can use variables defined in the component script, or other Astro components imported in it.
The CSS in the style tag is scoped to this astro component only.
The script tag at the bottom uses a special astro directive, and will be executed client-side.

Building a site using Astro components is much the same as using React components (or partials in other SSGs). But the real power is using them inside Markdown Content.

MDX Components

MDX lets you use JSX inside markdown files, and is one of the main reasons I chose Astro over other SSGs. In Astro, you can import .astro components into mdx files and use them in the same way you can anywhere else. I’ve ended up with quite a lot of really simple components which just render some HTML and apply some scoped CSS to it. Here’s my highlight.astro component:

<span class="highlight"><slot /></span>

<style>
  .highlight {
    background: var(--color-highlight-bg);
    padding: 0 8px 4px;
    border-radius: 4px;
  }
</style>

And now when I’m writing in markdown I can use it like this:

Here is some text <highlight>that is highlighted</highlight>.

And with more complex components like callouts…

<Callout emoji="💡" type="blue">
  Lorem ipsum dolor sit amet consectetur adipisicing elit. Earum hic a dolorem ipsa labore cum.
</Callout>

…which renders…

The combination of Astro’s component-based architecture and components-in-MDX-files ticks some important boxes for me:

Components make for easy maintenance long term, especially when dealing with CSS.
Scoped CSS and JavaScript mean I can iterate on styles without worrying about breaking other parts of the site.
Using components in Markdown makes it extremely easy and quick to write fully featured content.
If I ever want to switch away from Astro, the structure of Astro components and how they’re used in Markdown files should make it fairly easy to port my content to another system.

So Where Am I Now?

Two years into running this site on Astro, I’ve settled into a setup that gives me everything I need without much fuss.

Content Collections

The site uses two main collections: Articles and Notes. Articles are long-form pieces like this one – they live in /writing/ and support cover images, tags, and a bunch of other metadata. Notes are shorter, usually links to interesting things I’ve found with a bit of commentary. They’re deliberately minimal: just a title, optional source URL, and publication date. Both use the same filename pattern (YYYY-MM-DD-slug.mdx) which keeps things organised and makes it dead simple to create new content.

Plugins

I’m using a handful of plugins that handle the boring stuff so I don’t have to think about it:

Expressive Code handles syntax highlighting for code blocks.
Astro Icon lets me use SVG icons without manually importing and managing them. I can just drop <Icon name="heroicons:home" /> into any component.
Sitemap generates a sitemap.xml automatically, which is one of those things that’s trivial but annoying to maintain by hand.

On the markdown processing side, I’m using a few rehype plugins:

rehype-autolink-headings adds anchor links to headings (so you can link to specific sections)
rehype-external-links automatically opens external links in new tabs
rehype-mermaid renders mermaid diagrams at build time.

I’ve also got a custom remark plugin that calculates reading time for articles.

Components

I’ve got about fifteen components in src/components/mdx/ – things like <Callout> for highlighted notes, <Accordion> for collapsible sections, <BookmarkCard> for pretty link cards, and <Notion> for embedding Notion links. Nothing fancy – just small bits of HTML with scoped styles.

The page layouts are simple – components like BaseHead, MainNavigation, and Footer get composed into layout templates like Article.astro and Note.astro, which wrap the markdown content. The whole design system is based on CSS custom properties defined in global.css, so switching between light and dark themes (or tweaking colours) is just a matter of changing a few variable values.

Future Plans

There are some notes & ideas on GitHub, but I’m not in a particular rush to ship any of it. I’d rather spend my time working on Astro Editor or using it to write stuff here.

AI and ADHD

Thu, 10 Jul 2025 00:00:00 GMT

My friend Vicki’s “mate have you considered maybe youse got ADHD” was the first time I remember this topic coming up. That was six years back and I promptly forgot about it. Then two years ago – while ADHD was all the rage on TikTok – my friend Janina had a period of revelation about herself and made me do a bunch of tests. Turns out I probably have Adult ADHD.

I’m writing this because I read a couple of posts this week which got me thinking about ADHD again, and because I’ve been knee-deep in AI-related things for the last month. The article below is a response to DHH’s rant about ADHD, which I remember skimming last year. I only just found Schneems’ response, which had me in stitches more than once…

My Red Hot ADHD Programming 'Affliction'

Sorry, Dave, ADHD is real, and (not acknowledging it) can hurt you. Hi. I’m Richard. I’m a Ruby Core Contributor. I also code in Rust, and enjoy giving talks...

schneems.com

He makes a lot of good points, but two bits cracked me up in relation to myself…

My biggest behavioral issue was that I snuck books into class and read them under my desk. If your mental picture of someone with ADHD is an out-of-control “little monster,” then this seems like the opposite. I got through college with a degree, taught myself Ruby on Rails

I also snuck books into school to read under the desk. One teacher gave me detention for it. Others brought me really interesting books from home (in one case a giant stack of New Scientist magazines), and occasionally let me get away with reading over the desk instead of doing whatever I was supposed to be doing. And like Schneems, I also got through university with a degree and taught myself Ruby on Rails.

One day, I was having an argument with my wife. It was about how I never planned dates. It got heated. She had to go to a meeting, and I planned to return to the conversation “Hey, how about we grab lunch after your meeting to talk it over.” I realized that I needed to meet the basic expectations of planning events and trying to compensate for them by taking action then and there. The suggestion might seem trite or pandering, but she thought it was good and agreed.

An hour later, she walked into my office (garage), and I literally couldn’t remember why she was there. Or rather, I was in the middle of another task, and when she walked in, I had to rack my brain to quickly retrieve the info that would provide context to her: “I’m here.” It took a split second too long, and she noticed. Turns out that I don’t “have a good memory.” What I have is the ability to recall extremely detailed information about a situation, given that I’m primed with the context.

I laughed out loud at this for like five minutes. In the two years since my friend Janina made me do those tests, we’ve laughed a lot at how differently this stuff affects each of us. The venn diagram of our symptoms barely overlaps. What Schneems describes here is not a thing for her at all, but it very much is for me. Janina and I share a house, so she’s seen (and been frustrated by) many versions of this over the years. See also my ex-girlfriends. And colleagues. And friends. Every single person I sent that quote to laughed – especially at the last two sentences.

Those last sentences are a beautifully concise version of something I’ve always struggled to articulate about myself: “What I have is the ability to recall extremely detailed information about a situation, given that I’m primed with the context.”

You and me both, Schneems. You and me both.

Entirely unrelated, I stumbled upon this wonderfully creative site:

https://www.adhdexperience.com/ adhdexperience.com

Preview unavailable - click to visit

Once I’d stopped puzzling over how on earth this was built on Wix, I read the list of symptoms. It’s been two years since I read a list of ADHD symptoms and I properly chuckled at how many apply to me. I’ve circled those which I definitely experience (and I’m sure my friends would recognise) below.

Me and ADHD

When ADHD was all over TikTok, loads of friends were prodding me about getting a formal diagnosis. I didn’t seek one because knowing whether I Have ADHD or not wasn’t useful to me, and still isn’t.

Most people I know – when faced with mountains of evidence that you very obviously have ADHD – reacted with some version of “OMG this explains soooo much, this is really helpful to know”. And for most of them it’s been really fucking helpful.

My own reaction was one of mild interest. Because while “you very obviously have ADHD” was news to me, not one of the symptoms was news. I’ve always held the view that these “symptoms” were just kinda how my brain is. Sure, they make me super-shit at a bunch of things, but they also make weirdly great at other things. Whether I like it or not, they’re how my brain is. And always has been.

This muted reaction is partly because I’ve been an accidental stoic from a young age – I’ve always thought it insane to try to control the uncontrollable. Things are how they are and unless we can actually change them it’s better to embrace reality and look for what we can change. I can no more control the symptoms I circled above than I can my emotions. But I can control how I respond to them.

I realised years ago that my brain was a bit weird. I also learned that any attempt to fundamentally change it was utterly exhausting, felt turbo-shit, and – most importantly – didn’t work at all. And if I couldn’t change how my brain worked, the only sensible response was to happily accept reality, and focus on useful things I could change.

Which is why I read Getting Things Done as a weed-smoking seventeen-year-old: I had some vague notion that I couldn’t rely on my brain to stay organised. All my mates thought this was very weird. And when – like most folks who read it – I failed to stick to the “GTD Way” for more than a minute, I took the bits that actually helped me and left the rest behind. And I’ve kinda been doing that ever since.

The result is: I’m self-employed, work remotely for multiple clients and intentionally avoid anything requiring a fixed 9-5 or Mon-Fri schedule. I write everything down immediately, lest it’s gone when my mental context changes 10 seconds later. Every time-based thing goes straight in my calendar, which is always with me. I own an Apple Watch specifically to poke me when I have meetings. I’ve internalised a bunch of habits which keep my physical space tidy without any conscious mental effort. I have hard rules to avoid impulse purchases and hasty big decisions (fundamentally: “always sleep on it”). And I could go on and on…

The point is: I’ve been finding out how to work well with my own brain for decades. Far from being exhausting, the kinda stuff above is liberating when I get it right, because it feels easy for once. Figuring this stuff out, however, is often not easy. The hard work is always the figuring out, not the sustained doing. Because if sustaining a thing feels hard, I haven’t figured out the hard bit of it yet.

Whether you have ADHD or not, finding ways to work with your brain rather than against it will never be a bad thing. And after working heavily with AI for the last few months, I have some embryonic thoughts which I’ll expand on some other time.

Embryonic Thoughts on AI & ADHD

In no particular order, some embryonic thoughts on AI, me, and possibly ADHD…

1️⃣ A Focussed Context Window (for me, not the LLM)

When most folks get a WhatsApp message asking if they’re free on such-and-such date they’ll open their calendar app and either reply with an alternative date or add an event to their calendar, before closing it and carrying on with whatever they were doing before.

When I get a message, 50% likely to do exactly this. But in the other 50% I’ll catch sight of some unrelated meeting or event next week and my brain will instantly switch context to thinking about that. Worst case, this means I forget to deal with the message which caused me to open my calendar in the first place. Best case it takes 15 minutes to refocus my brain on whatever I was doing before.

And this applies to loads of shit. It’s why I check email at designated times and why none of my tech sends me notifications. This problem is easily solvable by deliberatly doing One Thing At A Time in an isolated context. Right now I’m writing this post in a super-zen minimalist editor precisely so I don’t get distracted.

But that’s not how most knowledge work works. Most work constantly requires context and information from places other than where we’re currently working – calendar, meeting notes, slack, notion, the web, etc etc etc etc.

So the real challenge for me here is creating an environment where I always have the full context I need for what I’m doing right now but nothing more.

While I can kinda do this manually it takes way more energy than it does for most folks, so I’m particularly excited about the potential for AI tools to help with this. Which is kinda amusing because – like me – LLMs also operate best when their context window contains exactly the right stuff.

2️⃣ Meetings Etc

Meeting recording and transcription tools are a big deal. For most of my life I’ve waged an internal battle between losing myself in the experience of a good meeting and ensuring something useful comes out of it after. Whether I’m stream-of-consciousness jabbering while excitedly hand-waving or listening rapt while others do so, I’m concious that creating & guiding effective conversation – and capturing the useful bits of it – requires skilled facilitation. I often end up in that role, requiring a decision on whether I want to do it well or fully participate in the conversation. Because I absolutely cannot do justice to both at the same time.

AI cannot ever replace skilled human facilitators. But in the (many) situations where my de facto facilitation role is just preventing unhelpful tangents and ensuring we remember the important bits after… AI can totally take the latter away from me during the meeting itself.

Paired with vaguely sensible meeting practices, AI tools like Notion’s meeting recorder have really helped me to stay present and focussed during calls.

3️⃣ Faster Side Quests

I’m certain there’s a subreddit dedicated to the partners of ADHDish people sharing funny-but-exasperated stories about this afternoon’s progression from quickly cleaning the garage to driving forty miles for a custom-machined nozzle for the tool that oils the leaf blower while the contents of the garage remains 50% organised and labelled in excruciating detail and 50% definitely not going back in the garage before nightfall.

I’m like this, and I fucking love it. I love that custom-machined nozzle and its metaphorical brothers. I could legitimately argue that my whole career has been a series of semi-random side-quests stacked on top of each other.

I’m lucky that given enough time I’m pretty good at working back up the chain of side-quests until eventually the garage ends up clean. But that often takes a bit too long, and I run out of time, and the stuff on the drive gets nicked or rained on otherwise ruined. If only today was longer and I had a floodlight etc.

LLMs won’t help me with my garage, but they can make a lot of computer-based side-quests waaaaaay faster. More importantly, they significantly reduce the time between me embarking on a side-quest and realising either A) it’s more than a side-quest and I should treat it as such or B) it’s not worth persuing. I’m talking weeks to hours in some cases.

TL;DR: LLMs have allowed me to follow side-on-side-on-side-quests and come back up the callback chain in a reasonable timeframe way more than I could before. Which is both fun and useful.

4️⃣ Context Switching When Bored

I get bored way to easily. But I also hyperfocus easily. I’m lucky enough that I’ve worked out how to blend those things into something which makes me good at learning things and doing things.

A large part of that is my ability to maintain focus on things in a macro sense over periods of time. But the one thing I cannot fucking do is maintain focus in a micro-sense when it’s gone. In the course of writing this article I’ve walked downstairs six times to smoke a cigarette and twice to make a cup of tea. I’ve folded five T-Shirts, weighed myself and noted the result in my journal and resisted countless urges to open a web browser.

None of those things took more than 5 minutes and none distracted my macro-brain from this article. But without them I’d have been impotently raging at my keyboard.

Because while I need that focused context window in a macro-sense, I need regular mini-distractions in the micro sense.

Surprisingly, I’ve found that doing at most two things at once with agentic AI tools ticks this box. I legit smoke fewer cigarettes when working on two unrelated tasks using AI agents. When I need a break from hard thinking about Thing A, I set an agent off doing something useful on it and context switch to checking in on what AI has done on Thing B. Prodding Thing B’s AI towards the next thing is just enough of a break to bring my brain back to Thing A. 🔄.

This only seems to work if Things A & B are not the same complexity. AI coding agents (in Aug 2025) don’t have sufficiently nuanced mental models to make non-trivial decisions about software engineering – nuanced mental models is my job as the human overseer. But if I’m doing that for Thing A, I need Thing B to need the same nuanced mental models I’d give to smoking a cigarette or making a cuppa.

When this works, context switching between two tasks improves my ability to focus on both. Which is new to me (despite many attempts to kid myself otherwise in the past).

Wrapping up…

Writing this has been weirdly cathartic because it’s the first time I’ve properly ordered any thoughts about this stuff. But also because whether we’re talking about AI or our own brains my parting message is the same…

This is what it is, and pretending otherwise is foolish. Our job is to work out how to use it in a way that’s positive for both ourselves and the wider world.

I don’t think AI will ever be better at 👆 than humans. Solong as we give it the time of day.

Personal CRMs Aren't What I Need

Mon, 05 Feb 2024 00:00:00 GMT

I paid a 12-month subscription for a Personal CRM called Clay because I need help “managing my personal and professional relationships”. It’s not bad software. BUT…

It turns out what I need is not Clay, or any other “Personal CRM” I’ve found.

It feels like most of these Personal CRMs are made by folks with very different problems to me.

I know a lot of founders, execs, freelancers (and salespeople) who are very good at building and maintaining their personal relationships… it’s a huge part of their job after all. Most of them reach out to people, meet new people and get/make a lot of useful intros on a daily basis.

For them, Clay’s features are probably pretty useful. I can imagine it’s useful knowing it’s Andy’s birthday today, and when you last spoke 9 months Andy was struggling with X, Y and Z and had a baby due in August. And that Andy’s job on LinkedIn changed 3 months ago. Etc. Because all that makes excellent context for a quick email to reopen a conversation.

If you read that and thought “well duuh what’s a CRM for?” you’re one of the founders/execs/freelancers/salespeople I’m talking about 👆. We probably agree that the job of a personal CRM is keeping information about the people you know organised, current and readily available.

Which is exactly what all CRMs are for… sales CRMs were originally designed to help salespeople manage exactly this kind of information in a sane way, making it easier to maintain meaningful contextual relationships with customers & leads.

But that’s not at all what I need from a “Personal CRM”. If it was I’d happily be using a janky setup of Hubspot, Zoho, Salesforce (💸) or similar to manage my personal relationships.

What I need is a tool that solves a different set of problems. I need a tool that makes maintaining and growing my personal relationships & network easy and fun. I need a tool for people who are not good at this stuff in the first place.

I need a tool that pings me before I meet someone new and suggests context-aware questions & conversation points. I need a frictionless way to note the important bits down and resurface them appropriately. I need to know when two of my contacts have something non-obvious in common, and an easy way to intro them. I need to be magically reminded that when I last spoke to Anna from Random Startup Ltd she was excited about her family trip to Croatia, and I want that reminder (with context) 3 days after she gets home – or when I happen to end up in Croatia myself.

When I meet people in real life I invariably have a million great conversations, intro people all over the place and get excited. I am by no means bad at building genuine relationships. I need a tool that helps me feel like that when I’m sat at my desk.

Most of all, I need a “Personal CRM” which solves an unsolved problem for me…

I need a tool that makes managing my network of personal relationships feel like the opposite of what salespeople use CRMs for.

I have a large extended network of people with whom I have potential mutually meaningful relationships. In sales parlance, they’re almost all “very warm”. But for the most part, none of us is trying to sell shit to each other. In common with a lot of other people in that network, I’m crap at maintaining the relationships that constitute it and even crappier at cultivating the second-order relationships that could expand it.

I need tooling to help me with that.

Since we’re discussing Personal CRMs, here’s a not-at-all-work-related take…

My housemate is amazing at maintaining her myriad personal relationships. Nothing to do with her work. She loves buying super-thoughtful presents for people she barely knows. She always remembers to invite randos from the pub to stuff they’d enjoy. She always remembers to message about important stuff in folks’ lives. And very quickly “barely knows” doesn’t apply. This is genuine relationship building done well.

Meanwhile I’m the opposite (I’d forget my own birthday if said housemate didn’t remind me). Sure, I could learn to behave like her, but it would never be natural and I’d never get off on it the same way she does.

It feels like every Personal CRM I’ve seen is designed for people like my housemate, or even worse… the I-Am-At-Work equivalent of her. ie. Folks who enjoy and are somewhat good at this stuff.

Perhaps obviously, it also feels like every Personal CRM I’ve seen designed by this kind of person.

And it feels like for this kind of person the core value prop of a “Personal CRM” has already been solved by CRMs in general. (Every good salesperson I know maintains a personal CRM of sorts… none use a specific Personal CRM tool.)

It feels like at best, a Personal CRM is slightly tweaked UX presented as a skin over an already-solved problem.

Meanwhile the problems I have are mostly unsolved by software. I signed up for Clay because I need help “managing my personal and professional relationships”. But what I need is not a tool like Clay. Because everything I said above.

And I’m convinced I’m not alone here. I know too many people like me who are excellent at building deep, meaningful relationships with a few people, but can’t bridge the gap to doing so more widely.

I’m equally convinced that none of us is likely to found a “Personal CRM” startup to address this.

But my goodness would we throw money at someone who did.

Does this chime with anyone else? 👆

PS. I’d love to see Clay’s churn data, segmented by a yes/no to “Do you enjoy buying gifts & organising birthday parties, and when you have amazing convos with people at conferences, do you message them afterwards?” Then label with potential high-value customer.

EDIT: Practical Example…

I bumped into Chase Warrington a bit ago. I’ve been a fan of Chase’s work for ages, and very much look up to him in a work context. He’s exactly the kind of person that should see me stuffing everything I know about him into my “Personal CRM” so I can extract the maximum value from our relationship.

But that’d be mental because neither of us are arseholes, we’ve got nothing to sell each other and fuck basing any relationship on the extraction of value.

I want a Personal CRM that’s like “Chase just interviewed someone you know on his podcast, you should listen to that one and then maybe WhatsApp them both?” or “Chase is in London right now and he’d definitely like this band you’re going to see tomorrow but FYI he’s here for a funeral”.

Building Healthy Remote Organizations - The Silent Enabler of Success

Thu, 10 Feb 2022 00:00:00 GMT

For a long time I’ve believed that organisational health is a hugely undervalued ingredient for success – especially for startups that are scaling fast. It’s the silent enabler of so much else. Before I give you my take on it, here’s a succinct definition of Organisational Health…

An organization’s ability to function effectively, to cope adequately, to change appropriately, and to grow from within.

For me it’s about intentionally creating a resilient, cohesive organisation that can operate with a sustained sense of calm.

Really healthy organisations tend to feel calm even when they’re ploughing through unknown waters at a thousand miles per hour. They’re able to operate on the edge of chaos without becoming chaotic.

Despite the obvious benefits of a healthy organisation, it’s often neglected – I think for a few reasons…

It seems kinda boring – we’re conditioned to believe the best solutions come from fancy, innovative approaches. Being healthy isn’t complex or innovative… but it does takes sustained effort. And there’s none of the adrenaline which usually comes with startup leadership.
It’s very hard to quantify results. The best measurements of organisational health are whatever we use to measure general success (growth, revenue etc) but this makes it very hard to measure the effect of work. As always, useful proxy metrics are hard to find.
It needs a holistic approach - it cuts across leadership, operations and people functions, as well as every other function in a business. Which makes it hard.
Founders are often unskilled in this domain – the skills needed to grow a healthy organisation often feel quite at odds with the other skills required to be a good founder. (Some only realise this when the wheels fall off but I’ve met a lot who realised from the start, felt horribly inadequate as leaders and stuck their heads in the sand.)

Remote and distributed companies need to be much healthier than office-based firms because co-location allows us to paper over an awful lot of cracks. And systemic health problems have a disproportionately large effect on remote teams, which quickly compounds with scale.

So what does a healthy organisation look like to me?

These kinds of things…

Happy, autonomous and empowered people (obviously).
A unified, coherent senior leadership team exhibiting all the traits & behaviours we’d expect of any other great team.
Common, well-understood shared norms, habits, behaviours & ways of working. (We could label this “culture”.)
Common, well-understood values and principles which facilitate aligned independent decision-making at all levels.
A clear, truthful and well-understood structure (org design, teams, career levels, salaries etc).
Excellent communication everywhere.
A culture that values clarity.
A culture of trust and psychological safety.
A culture that cares about how we work, and actively tries to make it better.
Systems, processes and tools that make it easy to “operationalise” repetitive work.
Managers who have the time, skill and motivation to lead and manage well.

None of these things happen by accident.

So when should you start thinking about organisational health?

Short answer: as soon as you reasonably can.

Small, young companies get disproportionally large gains from the effort, which compound over time. Without the right foundations this all gets exponentially harder as you scale (and as your collective habits and ways of working become entrenched). I’ve seen way too many companies ignore this stuff until they’ve raised a Series B and the wheels start falling off.

Having the foundations for a super healthy organisation allow you to scale quickly without as much pain, and help things stay calm as the organisation rapidly becomes more complex.

So how do we start getting healthier? 🌱

Firstly, we need to believe it’s at least as important as our other business aims. Being healthy is unlikely to be the number one goal but, as with human health, unless we make a strong commitment to it, it’ll always lose out to other more pressing stuff.

Secondly, we need at least one person who’s wholly focussed on keeping our organisation healthy. I’ve seen some amazing small startups where this is the fundamental job of the COO. More recently, I’ve seen this owned by a Head of Remote.

In larger firms I’ve seen teams called Workplace Design, Office of the COO, Remote Operations, People Operations, (plain old) Operations, and the like. The one thing these have in common is that they are 100% focussed on making the company itself as healthy as possible.

Ultimately, keeping an organisation healthy will always be a joint effort led by people like…

COO, VP Ops etc
CPO, VP People etc
Chief of Staff, Head of Remote etc
Leaders specific to the company’s core business (eg CTO for tech companies)

None of this happens by accident.

Guiding Principles 📜

Here are a few loose principles I’ve found useful for helping folks approach organisational health. (I could – and probably will – write a whole article on each of them.)

1️⃣ Have an internal focus

Most functions in a startup are led by external needs & drivers: Product, Engineering, Sales, Marketing, Strategy, etc… all should have their eyes set mostly on the outside world.

We need at least one function which has an internal focus, treats the company like a product, itself as a product team and its employees as users. And this function needs a good product manager.

Done well, this function is a huge force multiplier for all the others.

“We design how our company works as thoughtfully as our products.”

2️⃣ Beware organisational debt

Just like a software product accrues technical debt, a company accrues organisational debt. The effects are similar - it gets increasingly harder to get stuff done over time.

Used strategically, this kind of debt is useful because it lets us move faster, but the tweet below explains why we must be intentional about how we incur it. And how we pay it down.

The opposite of technical debt isn’t zero debt, it’s compounding gains: each new thing makes it easier and faster to build new things.
— Matt Wensing 🐙 (@mattwensing)
June 10, 2020

3️⃣ Human + System

These are the two fundamental components, and Internal Operations should focus on both:

Human - Relationships, culture, leadership, human growth, shared mindset, “vibes” etc.
System - Structure, process, policy, tooling, automation etc.

These need to be viewed and tackled together and the highest leverage stuff addresses both human & system concerns at the same time (eg. shared behaviours & habits).

4️⃣ Behaviours & habits over processes & tools

While processes and tools are important, the most effective way to improve an organisation’s health is by improving the habits and default behaviours of its people.

If you’ve ever tried to impose a new system or process without considering behavioural change, you’ve probably seen a lot of folks ignore it and revert to what they know. People always fall back on their habits and default behaviours. Especially in groups.

On the plus side, given the right habits, behaviours, principles, environment etc, people will likely create effective systems & tools on their own.

That said… used intentionally, processes and tools can be very powerful tools for affecting behaviour & habits. Especially in groups.

5️⃣ Strive for clarity

A culture of clarity reduces day-to-day uncertainty and tends plenty of efficiency savings (especially in distributed companies). But its greatest value comes from how it reduces the cognitive load on people.

At best, lack of clarity leads to increased cognitive load as folks struggle to make sense of things and make decisions themselves. At worst, it leads to a culture of uncertainty and stress because in the absence of facts people always assume the worst. In either case, it means people are spending a lot of time thinking and talking about unnecessary stuff.

Creating clarity in a complex and inherently unclear environment is one of the hardest things about leadership, so leaders often think about clarity in a very macro sense: is everyone clear on our mission? Or our Q3 goals?

Yet most of the uncertainty, inefficiency & stress I’ve seen comes from lack of clarity on tiny things:

I’ve found five different versions of this template and have two conflicting answers about which one to use here.
What’s this meeting about? I don’t really know what’s expected of me and what are these weird notes I’ve been sent all about?
Is it okay to expense my new headphones? How do I do that? Who do I even ask?
Who should I talk to on the marketing team about this thing? Misha told me Andy, but which Andy? He’s not on the org chart? Wait, is Marketing even the right team?

Creating clarity & consistency on stuff like this is often much harder than it seems – especially in large, fast-growing or globally distributed companies. But done right, it can have an insanely big effect on organisational health.

6️⃣ Practice simplicity

Simplicity matters because simple things are easy for people to fully understand and reason about. When designing systems we have to consider the usefulness and accuracy of the mental models folks form about them.

It’s much easier to augment folks’ existing correct mental models than to fix their incorrect ones.

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system. — John Gall (1975, p.71)

Designing simple solutions for complicated problems is almost never simple itself, but wherever possible we should aggressively err on the side of simplicity.

7️⃣ Harness the power of principles

Principles are often more useful than rigid rules because when they’re fully understood they allow people to confidently make decisions without constant recourse to others. They also help people understand the why.

Even when you need rigid rules, clearly explaining the principles which underpin them increases transparency & shared understanding, and helps folks to adapt the rules intelligently.

For any principles to be useful they need to be well-thought-out, easy to understand and constantly reinforced by everyone. Otherwise, they’re just more words in a document somewhere.

8️⃣ Create frameworks (as well as tools)

Our inwards-facing function needs to build an environment & toolset that helps other functions do their best work. But also go one step further and create the environment & meta-tools that allow others to design their own.

We can’t design an entire company from the top. Nor can we design by general consensus on everything. Instead, we need to provide a framework of strong, consistent guide-rails (principles, tools, practices, structures etc) that everyone trusts.

This is the kernel of our “Operating System”. If everyone really understands this framework and buys into it, (with a little help) they’ll be able to create their own systems of work on top of it. And our kernel helps keep those systems compatible with each other.

Doing this is the only real way to create a truly agile organisation that can evolve as it scales.

Of course, keeping the kernel fit for purpose takes ongoing effort. As does guiding and nurturing the people and systems that use it.

These are just a few of my thoughts on what it takes to keep an organisation healthy, but hopefully they’ve sparked a few thoughts for you.

If you take one thing away from this, let it be the idea that creating a great company only happens when we set out to do so with intentionally, and when we get it right the sense of calm it can provide is a silent enabler of so much else.

And with many of us moving towards remote, globally distributed organisations, all this matters much more.

Website Redesign Part XVI - A Header and Footer for Articles

Sat, 29 Aug 2020 00:00:00 GMT

I pretty much finished designing the article pages back in Part XI, and after deciding on a typeface and some general design rules for the rest of the site it’s time to finish it off by adding a header and footer to the article pages.

The Article Header

Here are a few ideas I played around with for the header.

Although I quite like some of these, it feels like I’m overcomplicating things a bit. It might be better to go with something really simple for now – just a link back to the homepage in the top left corner.

The Article Footer

The footer needs to include some links, my name and a copyright notice. After a little playing about I ended up with something like this…

While I like this, it needs more thought to make in work well on small screens, and I’ll be a challenge to implement without overcomplicating the code because of how I’ve set up the article CSS. So much like the header, I think it makes more sense to keep things simple and just provide a link to the articles index, rather than listing related/recent articles. I expect I’ll revisit this in the future.

The Code

Here’s what I ended up with for the CSS…

There’s definitely some scope to simplify this, and to add some more “features” to the footer, but this feels like it’s enough to call the articles done and move on to the rest of the site.

Auto Generating Jekyll Posts that Redirect to Medium

Thu, 13 Aug 2020 00:00:00 GMT

I’m making quite heavy use of the jekyll-redirect-from plugin. This allows me to create a normal apge or post file with a special frontmatter item and have the page 301 redirect to the specified URL. I’m already using this to forward URLs like <danny.is/using> to Notion, but I also want to use it for blog posts that I’ve written elsewhere.

I’ve recently written an article for Delocate, and I can quickly add that to this site by creating a file in _posts called 2020-07-31-not-all-comms-needs-a-purpose.md with the following frontmatter.

title: Not all communication needs a definite purpose
redirectURL: 'https://www.delocate.co/blog/not-all-communication-needs-a-definite-purpose'
platform: delocate

The post will behave totally normally as far as Jekyll is concerned, but instead of rendering the empty body, it will 301 redirect to the specified URL.

Although I’d like to move all my medium posts over to this site in the end, that’s a big job. So for now I want to create a file like this for every medium post I’ve written. Creating 40 of these files by hand isn’t very appealing, so I whipped up a quick ruby script to do it for me.

I started out trying to parse medium’s RSS feed but it doesn’t include all the posts, so I’m using medium’s private API instead. The script hits the medium API, extracts the data I need into an array and then loops over it creating a correctly formatted file for each post. It lives in scripts so I can run it whenever I want with ruby ./scriipts/generate_medium_forwards.rb to pull any new medium articles in.(If the whole Medium class seems like overkill, it’s because I based this on some old code that was more reusable.) Here’s the code…

This worked a treat and I only had one hiccup: I spend far too long trying to work out why many of the articles had identical published_at dates before I eventually realised that I needed the firstPublishedAt value rather than the publishedAt one – the latter gets updated every time the post is edited and re-published.

Website Redesign Part XV - A typographic system for the rest of this site

Wed, 12 Aug 2020 00:00:00 GMT

When I started this redesign I already had a fairly clear idea of the aesthetic I wanted, based on the existing design. These two pages show that off quite well.

I’m not sure where I got this aesthetic from, but it’s clearly draws on the work of Jan Tschichold. Jan was a typographer and designer who’s famous for a whole load of stuff (go read his Wikipedia page). I particularly like this style, which is closely associated with him.

I spent quite a while trying to establish some sort of typographic hierarchy for the rest of the site based partly on some thoughts from my last article. Eventually I realised that this is really hard when I’m going for a deliberately “whacky” aesthetic. The kind of style I’m after doesn’t lend itself well to rigid hierarchy. And the fact I’m likely to size some type with viewport units makes this approach even less sensible.

So I went back to square one and decided on a few guidelines and constraints in place of a hierarchy:

Use type and layout over imagery and effects.
The site should always look good in greyscale. While I can use colour, it should never be the main design element.
One typeface only, but I can use it in any weight or size that feels right.
Always consider visual hierarchy, and be consistent across pages where possible.
A grid of 20px, but with permission to ignore wherever it makes sense.

I also settled on a modular component-based approach where possible, and identified a few core components that will be useful in all sorts of contexts going forward. They’re deliberately simple and extensible in their design.

Deciding on a typeface

I spent way too long choosing a typeface for articles, so I’m keeping the simple. I decided to stick with Futura PT. It works perfectly for the look I’m going for and looks good in all caps, which I’ll probably be using a lot. This choice has some downsides though: the biggest being that it’s not available for free so I’d have to keep my Adobe Fonts license and accept the dependancy on Adobe’s service.

I’d pretty much decided to suck that up when I discovered Jost*. It’s a pretty close match for Futura, is open source and available as a variable font. It’s slightly larger than Futura but after a bit of trial and error I think it’s a good trade-off.

Text Styles & Components

With that decision made, I threw together a few basic components and text styles in Figma. there’s no real system for this – I started with the components, extracted text styles from them and then did my best to consolidate them a bit.

Having these styles and components is a great starting point for some experimentation. I’m gonna hold off coding them up until I’ve done a few iterations in Figma – I’m sure they’ll change a little bit as I play with them. The only technical work I’ve done is to build Jost’s variable version from source and bring it into my site.

Website Redesign Part XIII - Taking Stock of Content

Sun, 12 Jul 2020 00:00:00 GMT

I’m now pretty happy with how the essays on here look, so it’s time to turn my attention to the rest of the site. Although I have an idea of the aesthetic I’m after, every time I’ve opened Figma to have a play I’ve found myself staring at a blank page wrought with indecision – the dreaded writers block. Or rather, designers block.

I didn’t feel this at all when designing the essay pages because I had a clear idea of what I was trying to do. I already had content to work with and my only job was to make it as readable and beautiful as possible while keeping things simple. Clear goal. Clear starting point.

But with the rest of the site it’s not so clear. In Part IV I identified a list of pages I need to design, and I did some high-level pondering on goals and user needs in Part II. But beyond that, I’ve basically got no constrains and no starting point. And it’s paralysing me.

Back when I made websites for a living, the first thing I’d look at after user goals was a content audit. If the client didn’t have any existing content to audit, we’d focus on the content they thought they were going to have. So that’s just what I’m going to do now.

A Content audit for this site

I can think of a hundred other things I might want to put here someday, but that’s all the stuff I’m thinking about putting here right now.

Organising the post-its

Let’s take a stab at organising these post-its according to a few different taxonomies. This might seem like overkill for such a small set of content but this exercise often throws up unexpected and creative ideas for organising and grouping. Even if we don’t use them, they can help seed concepts we use elsewhere.

By type

Let’s start with the most obvious, grouping by content type – the first word of each post-it is a good starting point. We could also group by whether the content is mostly writing (yellow) or mostly something else (orange).

By author

I’ve been thinking a lot about the creation and consumption of information lately, so it’s not surprising this springs to mind as a possible grouping: did I create it, or did I consume it? Some stuff is hard to categorise here – a book recommendation is clearly consumption, but what if I add my own review?

By professional or personal

Since this is a personal site, we could consider grouping the content by whether or not it’s related to my work.

It’s pretty obvious that most of the content types here are focussed on my work. Looking at the both pile, the vast majority of content represented by each post-it is work-oriented. (While I do read some non-work articles via pocket, they’re in the minority. Likewise for articles on this site. Etc.)

So this grouping doesn’t feel very useful. Moreover, it doesn’t feel authentic – I’ve always mixed work and play and I’m not really sure where the line between them is. That solitary orange sticky note makes me question whether my music videos belong on this site, though.

By Importance

Some of these post-its are more important to me than others. My writing – whether on this site or elsewhere – is pretty core. As are links to my series’ on Notion. But the books I’m reading are much less important – I could live without having them on this site at all.

Perhaps the design should emphasise the important and de-emphasise the less-important? Or perhaps the less-important shouldn’t live here at all? My view of what’s important is almost certain to change over time, so if I do emphasise some content based on this it should be easy to change.

By Permanence

One of the main reasons I’m moving my writing to my own blog is permanence. I don’t like the fact that Medium controls my content and URLs. I want a more permanent place to put my words. Somewhere they can live forever – etched in stone, as it were.

The same is not true for other types of content. My tweets are ephemeral, for example: I wouldn’t be overly bothered if they all disappeared one day. Perhaps we could try grouping along these lines – stuff that I care about keeping vs stuff that I don’t.

But what about the actual content?

If you’ve ever done any information architecture you’re probably shouting at your screen right now…

BUT YOU HAVEN’T CONSIDERED ANY ACTUAL CONTENT! It doesn’t make sense to group based solely on medium.

You’ve got a point.

It’s kind of ridiculous to go through this exercise based only on the medium in which the content exists. We should also be considering things like subject area, target audience and purpose. For large sets of information these things will probably suggest much more useful taxonomies than content type.

I’ve ignored these so far because I don’t want to base the structure or conceptual design of this site on the topics I’m currently engaging with. I know too well how quickly they can change, and it’s important this site can adapt to those changes without much effort on my part.

Having said that, I’d be foolish not to at least consider the kind of content I’m producing right now. For the past few years, my interests – and especially the stuff I write about –have fallen in one of four loose categories.

I’ve started to loosely group these into two super-categories: Human and Systems. The first includes everything where an actual human is the focus – think coaching, mentoring, nurturing etc. The second is focussed on the environment in which humans operate and how it can be engineered to provide the most useful support. I’ve been doing a lot of gardening during lockdown, so if you’ll excuse the metaphor…

Caring for a garden requires system design and engineering. Plants need the right soil, pots and sunlight. Some need the support of a rigid framework like a trellis. Growing from seed often means adherence to a thoroughly-researched process of feeding and repotting. But on its own, this stuff can’t possibly create a beautiful, thriving garden. Plants need to be nurtured and guided, and they won’t always do what we expect. As gardeners, we must observe individual plants and do what’s best for them, using our intuition and experience to guide us.

A creeper might grow without a trellis, but it will be in a random direction and will have to work much harder to get up the wall. But a trellis is useless without daily watering and occasionally guidance. And sometimes a creeper will ignore the trellis and decide to weave beautifully around a fence instead. It’s up to us to notice where it’s heading and either correct or encourage it. And perhaps remove the trellis, if it’s not proving useful.

Like creepers, people need trellis’. They’re the systems, habits, processes and frameworks that support us and make our lives easier.

We also need nurturing and the freedom to explore our own path. If we have good gardeners looking after us, we can rely on them to guide and prune as needed, and to move or replace the trellis when it isn’t helping.

The more I reflect, the more sense these two categories make to me. Both Human and Systems work need to be in balance, and my interests can be sorted fairly well into those two buckets. (It’s interesting that the least happy bits of my career have occurred when I’ve been too focussed on one or the other)

I’ll explore this idea further outside the context of this redesign, but it provides a reasonable starting point for a top-level grouping of my content.

How is all this useful?

What can we take from all this, and does any of it help with my designers block? This process has certainly sparked a few interesting thoughts which I’ll definitely come back to in the future. It’s also sparked a few that are useful now.

Grouping by type provides a good indication of the components I should think about (Link, Video, Book, Page, Article, Other), but is not useful as a way of actually organising content.

Grouping by author raises the possibility of subtly differentiating content I’ve created from content I’ve consumed/curated. I’m not sure how useful this distinction will be for readers, but it still appeals to me as something to consider.

Grouping by professional/personal isn’t really useful, though perhaps my music doesn’t belong on this site and I should just link to youtube.

Grouping by importance raises the need for flexibility. I need way of focusing attention on stuff that’s important to me right now, knowing it might change over time. This might be as simple as moving stuff that’s currently important to the top of some list, but this has design implications. It should be easy for me to promote/highlight different types of content as my needs change.

Grouping by permanence doesn’t feel very useful at all.

Grouping by Human/System, and by the four categories of content feels like a good starting point for some labelling system which I should explore further.

Keeping it simple

Simplicity is a the core value of this redesign and working through this process has helped me reach a few decisions about how to simplify things.

I’ve no need for a coaching page right now. I can add this in the future.
I still want a hire me page but it makes much more sense for this to live in notion. I’ll forward https://danny.is/lookingforwork and https://danny.is/hireme to a public Notion page and be done with it.
I won’t show any actual videos on my site. Instead, I’ll present any video series’ as links to notion pages or YouTube playlists. I already have these set up.
I won’t have a page for my music. I’ll just forward https://danny.is/singing to my dormant youtube channel. I will show this link on the homepage, though – singing is a big part of who I am.
I won’t worry about notes for the moment¹. They’re an important part of how I’d like to share content but aren’t a priority and Notion might well be the best place for them.
I don’t care about books at all right now. If I really want to write a book review I can just write an article.
Core design concepts should be expandable to accommodate the unknown. For example, these would be bad ideas:
- Deciding I have three main types of content and basing my entire design concept on “threes”.
- Having all my videos on youtube and Loom, and using their brand colours as core design elements.

Wrapping up

I started this article as a way to get over writer’s block, hoping that a content audit would help provide a few constraints and possible design directions. It’s been an interesting little exercise and has definitely helped unblock me, but when I think about it all I’ve really done is intentionally focus my attention the same problem I had in the first place: what should I have on this site and how should I organise it?. So while this “content audit” was interesting, its real value came from forcing me to consider this problem in a structured, systematic way.

If you’re wondering what I mean by notes, I used to use tumblr for this sort of thing. ↩

Website Redesign Part XIV - Stepping Into Figma

Sun, 12 Jul 2020 00:00:00 GMT

Figma is one of my new favourite tools. I’ve been an avid fan of Sketch since I first picked it up in 2011. Compared to the other tools available at the time, it was a breath of fresh air. I still remember how excited I felt after I first used it for some actual work.

The first time I used Figma I had a similar feeling. Everything was just easy. Coming from Sketch, Figma felt comfortable and a lot of the keyboard shortcuts are the same so no need to reconfigure my finger-memory. Figma has some major advantages over Sketch. It’s web-based so it runs on any machine with a browser and my files live in the cloud by default. Anything I can do to simplify my laptop’s setup is a win for me. It also has great multiplayer – working collaboratively is an absolute joy. And it feels simpler than Sketch. The interface feels more intuitive and the way it handles components feels way more natural. So I’m now using Figma for pretty much all my design work.

Until now, I’ve been designing this site in the browser and haven’t felt the need for a design tool. But now I’m getting to the rest of the site, I know I’ll want to experiment with layout and colour faster than CSS allows. I also want to explore Figma’s component and shared styles features and this feels like a good excuse.

Text Styles

We can recreate the styles for these essays pretty easily. If we assume 16px as our base font size, it’s just a matter of doing some maths based on the em values in our CSS to get the size and line-height of all our text styles. Figma also lets us control some of the more advanced font features we’ve been using in our CSS.

With very little work, we can create a styleguide and create corresponding text styles. Here’s what I ended up with.

Colour Styles

While I haven’t given much thought to colour there are a few colours that I’m using in the CSS, so it makes sense to create some named colour styles and a palette in Figma too.

Grids

Since the line-height for my essays is 1.5, the baseline grid is 24. I use this measurement quite a lot in the CSS already, both for horizontal and vertical spacing. Figma allows us to create grid styles which we can apply to frames. Let’s create a simple grid style for 24px, and use it to position some content on the grid.

We can also create a grid that represents one line-height’s worth of padding around a frame, like this.

The trick is to create two grids, one Rows and one Columns, both with the same settings:

Count: 1
Type: Stretch
Margin: 24 (your desired padding)
Gutter: 0

Then we can combine both grids by creating a Grid Style that includes them both. And voila, we have a grid that we can apply to any frame to give us the correct guides for padding.

Components

Before we can call this minimalist design system done, we need to account for a couple of components that we can’t create using text styles alone: code blocks, blockquotes, lists and horizontal rules. We’ll create these as components, using the text and colour styles we’ve already defined. By using constraints we can ensure the content adapts properly as component instances are resized. Here’s what I ended up with.

Summary

None of this is especially useful right now, but it’s provided a starting point from which to design the rest of the site and taught me a few things I didn’t know about Figma.

Website Redesign Part XII - Responsive Images

Wed, 01 Jul 2020 00:00:00 GMT

The last time I built a content-heavy website, responsive images weren’t really a thing. In fact they were a definite problem for most developers. We could control the visual size of an image with percentage widths and media queries, but we had no easy way of controlling the actual image used by the browser. The easiest thing to do was just supply a very big high-res image that would look good on wide viewports and accept that smaller viewport devices would end up downloading a file with more detail than they could use.

The last time I gave any real attention to this problem I was working on a site with a lot of high-res background images. I dealt with it in three ways. Firstly, I used a jpeg that was too big for even the largest viewport, but with JPEG compression turned all the way up. This was then scaled down with CSS. This actually reduced the file size, and generally looked pretty good – even on new-fangled retina screens¹.

Secondly, I spent ages blurring parts of the image in photoshop. The idea was that the fewer individual colours there were in the JPEG, the smaller the filesize. Take a look at this photo:

There are probably hundreds of different shades of blue and grey in the sky, each one taking up bytes in the JPEG. By blurring the sky as much as possible, we end up with far fewer shades of blue and so reduce the filesize. Doing this was a pain in the arse.

All the other stuff involved swapping out images with javascript.

Thankfully that was ages ago, and we now have some much better ways of handling responsive images. Both secret and the <picture> element were being talked about when I stopped making websites for a living, but both are now well-supported by modern browsers.

SRCSET

The srcset attribute allows us to specify different image files to use at different resolutions and viewport widths. It looks like this.

<img src="small.png" alt="..." srcset="medium.png 1000w large.png 2000w" />

This uses the small version by default, but on larger screens the browser will download and use either the medium or large version of the image. All we have to do is make the three versions and bung them in our /images folder.

The general rule here is to use an image of the same dimensions as the original and just scale it down to make the smaller versions. As Chris Coiyer says:

Most responsive images uses will be: “I have multiple versions of this graphic. Here they are, use the right one.”

The picture element

The picture element is far more powerful, but also more complex. It allows us to do a bit more at direction as our image size changes – we can use images of different dimensions and control how they are displayed using media query-like rules. A quick google will turn up umpteen articles on how to do this.

Images on this website

Right now, most images on this site are included via standard markdown image tags, and the generated HTML is pretty simple:

<img src="/uploads/an-image.png" alt="An image" />

By default, these images would display at their natural size, so we’re using some CSS to constrain them to 100% of their container.

img {
  display: block;
  max-width: 100%;
}

Inside essays, this means that smallish images display at their natural size and will not be stretched (we’re using max-width not width), but very large images will be scaled down to fit in the essay container.

The problem with this is that I often include quite large high-res images and set them to full-bleed (more on that later). This is fine for large viewports, but smaller devices will be forced to download the massive high-res file.

The obvious solution is to generate smaller versions of these high-res images and then use srcset to let the browser decide which one to show. Except that this is a blog. And if I have to create multiple versions and write a long chunk of HTML every time I want to include an image in my markdown I’ll just stop writing altogether. Clearly, we need a way to automate this.

While we’re at it, there are a few other things we should consider. Firstly, it’s a good idea to explicitly declare the dimensions of an image in the HTML using the height and width attributes. Assuming we don’t override it with CSS, this prevents reflow by telling the browser how much room the image will take up so it can draw the right sized box before the image has downloaded. So while we’re automating image things we should probably add hight and width to image elements.

What’s more, modern browsers will soon be able to infer the aspect ratio of an image based on these attributes, and use that to draw a correctly-sized content box even if we’ve changed the width with CSS. Cool.

Secondly, HTML now supports native lazy loading via the loading attribute. This is obviously good for performance and is as easy as adding loading="lazy" to our image tags. Addy Osmani has a much more detailed explanation.

This ten-minute video from Jen Simmons foes a great job of explaining how all of this works.

How do we automate this stuff?

Good question. Back when I started this redesign, I made the decision to keep the tech super simple. Here are the principles I defined:

As few dependencies as possible (both build-time and run-time dependancies).
Use defaults wherever possible.
Write as little code as possible.
Do not over-abstract. Avoid fallbacks, polyfills and hacks.
Bake accessibility in.

I really don’t want to add unnecessary complexity to this site. But it feels like this is important enough to add a just little more complexity. If there’s a jekyll plugin that can read my markdown image tags, generate smaller versions of my images and insert appropriate srcset attributes, I’ll take it. Bonus points if it can add width, height and loading attributes too.

My initial search actually led me to some awesome plugins for Eleventy. This one does some cool lazy-loading with javascript and data URLs, this one creates picture elements, this one does just what I want for cloud-hosted images and this one basically does what I want but without the bonus points.

Reading though the source code of these was super interesting, and had nudged me to look further at Eleventy (there are some strong arguments for moving this site to it). But since we’re on Jekyll here, none of these are much use. What we need is the Jekyll Responsive Image plugin.

This looks like it solves half the problem. It lets us specify our own template for the generated image HTML which means we can add width, height and lazy loading ourselves. The only downside is that we have to use a liquid tag rather than standard markdown to insert images. No thanks.

And then jekyll hooks came to the rescue with this tutorial from Ivo Valchev. Let’s walk through the process…

Install the stuff

The plugin uses Rmagick which is a wrapper around imagemagick which is – and has always been – a nightmare. So first step is to update or install it and then try installing the gem manually.

brew install imagemagick
gem install jekyll-responsive-image

Now we can add it to our Gemfile and Jekyll config as per the README. There are a lot of config options available but I started with these: a path to the template, the sizes to generate and an instruction to only save the generated files in the build folder.

responsive_image:
  template: _includes/responsive-image.html
  sizes:
    - width: 480
    - width: 800
    - width: 1400
  save_to_source: false

How we need to create our template. I stole most of this straignt from the docs, but I’ve added lazy loading and width/height attributes.

{% raw %} {% capture srcset %} {% for i in resized %} /{{ i.path }} {{ i.width }}w, {% endfor %} {%
endcapture %}
<img
  src="/{{ path }}"
  alt="{{ alt }}"
  loading="lazy"
  srcset="{{ srcset | strip_newlines }}"
  width="{{ original.width }}"
  height="{{ original.height }}"
/>
{% endraw %}

So far so good. We can now insert responsive images with

{% raw %} {% responsive_image path: image.jpg alt: "My Image" %} {% endraw %}

To get this working with standard markdown, we need to register a hook that replaces markdown image syntax with this new tag at build-time. We can create _plugins/img_tag_transform.rb and add the following.

Jekyll::Hooks.register :posts, :pre_render do |post, _payload|
  docExt = post.extname.tr('.', '')
  post.content = post.content.gsub(/!\[(.*)\]\(([^\)]+)\)(?:{:([^}]+)})*/, '{% raw %}{% responsive_image path: \2 \3 %}{% endraw %}')
  post.content = post.content.gsub 'path: /', 'path: '
end

It’s a bit hacky, but it works.

Is it worth it?

My biggest concern with this approach is the added complexity. Not only have I added Imagemagick as a dependancy, I’ve also added a new jekyll plugin and a slightly hacky custom plugin.

For now, this feels like an acceptable trade-off, but if I find myself adding more similar stuff in the future I’ll have to revisit this and reconsider the value/complexity ratio.

Full-bleed Images

While we’re on the subject of images, I’ve also added a few utility classes to make my images a little more interesting. Normal images are constrained to the width of the element they appear in, but sometimes I want full-bleed images that extend out to the edges of the viewport, like this:

We can do this with a utility class and some calc() magic.

.essay {
  .full-bleed {
    width: 100vw;
    margin-left: calc(50% - 50vw);

    // For images that are not wide enough to fill the gap
    display: flex;
    justify-content: center;
    align-items: flex-start;
  }
}

These styles are applied to the container rather than the image itself so that images smaller than the container are never scaled up. We can apply this style in markdown like this

{% raw %}
{:.full-bleed}
![Image](/uploads/2020-07-02-hot-air-baloon.jpg)
{% endraw %}

Which will produce the following HTML

<p class="full-bleed">
  <img src="/uploads/images.jpg" alt="Image" ... />
</p>

As well as full bleed, I’ve also added classes for left and right bleed

.essay {
  .left-bleed {
    margin-left: calc(50% - 50vw);
    display: flex;
    justify-content: flex-end;
    align-items: flex-start;
  }

  .right-bleed {
    margin-right: calc(50% - 50vw);
    display: flex;
    justify-content: flex-start;
    align-items: flex-start;
  }
}

Summing up

Although it’s ben years since I’ve built a proper website like this, I’ve kept myself fairly up-to-speed with developments in CSS. Digging into responsive images has been a nice reminder that there is a whole raft of standards that I’ve ignored and know very little about. I’m now itching to explore some of the other stuff that I remember being discussed and has since matured. I expect I’ll have a play with with SVG (a lot has changed), web components and browser APIs for audio, motion and the like sometime.

That said, it wasn’t really my intention to go this deep into any performance-related stuff at this stage of the redesign, so while I’m tempted to follow up on this with a load more optimisation I’m gong to force myself back into design mode for a little while and focus on getting the non-blog bits of the site looking nice. Until next time.

There was an excellent article on this at the time, but I can’t seem to find it. ↩

Website Redesign Part XI - Code Blocks and Section Rules

Sun, 28 Jun 2020 00:00:00 GMT

I spent a long time [deciding on a typeface]({% post_url 2020-06-20-website-redesign-v %}) for these essays and I don’t want to spend nearly as long on code snippets. Although this series involves a lot of code snippets, I generally write about code a lot less than I used to, so it doesn’t make sense to spend ages on this. I use the wonderful Operator Mono in my text editor and I briefly considered paying for a web license so I could use it here too. But while I love it, it’s quite unusual and is definitely not suited to everyone’s taste. Both the typeface itself and the act of buying a web license are the opposite of simple, one of my stated values for this site. So instead, I’ll stick with the same requirements I used before: open source, ideally with variable and static versions, with nice ligatures and a range of weights.

The first thing that came to mind was Fira Code, an extension of Mozilla’s Fira Mono which was designed specifically for legibility. Fira Code adds a bunch of ligatures for character combinations commonly used in programming, as well as making a few adjustments to make code more readable.

The CSS

Although Fira Code is available via google Fonts it doesn’t support all the opentype features I want, so I ended up cloning the repo and moving TFF, WOFF and WOFF2 versions into the the assets folder like I did for Literata. They’re included in webfonts.scss and have a custom property set just like the other fonts too.

:root {
  --font-code: 'Fira Code', 'Inconsolata', monospace;
  @supports (font-variation-settings: normal) {
    --font-code: 'Fira Code Variable', 'Inconsolata', monospace;
  }
}

Since we want to use Fira code everywhere there’s code, we can set this as the default font for all code elements, whether inside essays or not. We can also use some of the advanced stylistic settings to turn on a sans-serif lowercase ‘r’ and put gaps in double equals signs. I think this makes code a little more readable.

code {
  font-family: var(--font-code);
  font-feature-settings: 'ss01', 'ss08';
  // sso1 = sans-serif lowercase "r"
  // ss08 = Gaps in double/tripple equals
  // See https://github.com/tonsky/FiraCode/wiki/How-to-enable-stylistic-sets
}

Fira code has a bunch of other features like this

Styling inline code

We’ll set the font size to the same as the samm-caps we’re using for abbreviations, which is about equal to the x-height of the body copy. Adding a border, background and a little padding to the left and right is the simplest thing I can think of to differentiate inline code snippets. We’ve also prevented breaking spaces with white-space: pre, though I might need to revisit this if I end up writing some very long inline code snippets.

.essay code {
  font-size: 0.85em;
  padding: 0 0.5ch;
  background-color: rgba(0, 0, 0, 0.05);
  border: 1px solid rgba(0, 0, 0, 0.1);
  border-radius: 1px;
  white-space: pre;
}

Styling code blocks

We already set up some basic styles for <pre> elements, so all we need to do is remove the styles we just set for any <code> elements that appear within them.

pre {
  border: 1px solid rgba(0, 0, 0, 0.2);
  padding: calc((1em * var(--base-lh)) - 2px);
  background: rgba(0, 0, 0, 0.05);
  overflow-x: scroll;

  code {
    padding: 0;
    background-color: transparent;
    border: none;
  }
}

The final thing to do is add syntax highlighting. Since we’re using Jekyll, any fenced code blocks that have a language defined on them will use Rouge to apply syntax-highlighing classes in the same way Pygments does. This means we can take an existing theme stylesheet and include it in our bundle. I used this one and tweaked a few of the colours slightly. I’ll come back to this once I have a colour palette for the site.

Horizontal Rules

I’ve always liked the section mark (§) and thought it might be nice to superimpose this on horizontal rules. The code for this is pretty simple – we’ll add a psuedo-element containing the mark and use flexbox to position the hr and psuedo element on top of each other. A bit of padding and a background on the psuedo element creates a gap in the line, and a little nudging with translateY vertically centres the mark.

.essay hr {
  display: flex;
  align-items: center;
  justify-content: center;

  border: 0;
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  &:before {
    content: '§';
    transform: translateY(-0.15em);
    background: var(--color-white);
    padding: 0 0.5em;
  }
}

It would also be nice to add a little more margin than usual either side of the rule. Since we’re using only top-margin to maintain vertical rhythm, we need to use the sibling selector to add margin to the element immediatly following the <hr> as well as the rule itself.

.essay hr,
.essay hr + * {
  margin-top: calc(2em * var(--base-lh));
}

Website Redesign Part IX - Lists

Thu, 25 Jun 2020 00:00:00 GMT

Lists are incredibly useful for certain sorts of article. I tend to make quite heavy use of lists in some of my articles, so it’s important that I give some thought to how they’re styled. Since I’m going for a “bookish” vibe, I’d rather keep the vertical rhythm the same as for all the other text on the page, so I’ll be sticking with the standard top-margin of 1 × line height and leaving the margin and line height of the list items as they are. With that decision made, we only need to worry about styling the list markers: bullets, numbers and checkboxes.

After a bit of playing around, I think it’s a bit too jarring to hand the markers in the margin and flush-align the text. If this was for print it might look less wierd, but we’re so used to seing indented lists on the web that it just feels wrong for this medium. So we’ll aim to flish-align the markers and set 1em of left-padding on all list items. As long as we keep the markers set to outside we’ll end up with the start of out text neatly aligned at 1em from the left margin.

.essay li,
.essay li {
  padding-left: 1em;
}

Bulleted Lists

After a bit of playing around, I’ve decided to keep the bullets super sumple. We’ll just use a mid-sized bullet and ad a little left padding to pull them inline with the margin.

.essay ul {
  padding-left: 0.4em;
  list-style-type: '•';
}

Annoyingly, iOS Safari and Chrome don’t yet support string values for list-style-type, but since they both support @supports, we can add a fallback.

@supports (not (list-style-type: '•')) {
  &:not(.task-list) {
    // Begin fix for browsers that don't support list-style-type: <string>
    list-style-type: none;
    padding-left: 0.9em;
    li {
      padding-left: 0.5em;
      position: relative;
      &:before {
        content: '•';
        position: absolute;
        left: -1em;
      }
    }
    // End fix
  }
}

Numbered Lists

We’re decreasing both the size and optical size for numbers to the same as we did for for abbr elements, and falling back to the Literata Caption if variable fonts aren’t supported. We’re also making them slightly bolder than abbreviation since, as markers, it’s important they stand out a little more. We’re then adding some left padding to bring the first character inline with the left margin: single digit numbers will be flush with the margin while extra digits will extend outwards to the left.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam tincidunt mauris eu risus.
Vestibulum auctor dapibus neque.
Nunc dignissim risus id metus.
Cras ornare tristique elit.
Vivamus vestibulum ntulla nec ante.
Praesent placerat risus quis eros.
Fusce pellentesque suscipit nibh.
Integer vitae libero ac risus egestas placerat.
Vestibulum commodo felis quis tortor.
Ut aliquam sollicitudin leo.
Cras iaculis ultricies nulla.
Donec quis dui at dolor tempor interdum.

.essay ol {
  padding-left: 0.8em;

  ::marker {
    font-size: 0.85em;
    font-family: 'Literata Caption', Georgia, 'Times New Roman', serif;
    font-weight: 600;

    @supports (font-variation-settings: normal) {
      font-family: 'Literata Variable', Georgia, 'Times New Roman', serif;
      font-variation-settings: 'opsz' 10;
      font-weight: 610;
    }
  }
}

Checklists

Jekyll allows us to use Github Flavoured Markdown task lists, and I occasionally make use of this in my articles. They work like this

- [ ] Item 1
- [x] Item 2
- [ ] Item 3

This will produce the following output and HTML

Item 1
Item 2
Item 3

<ul class="task-list">
  <li class="task-list-item">
    <input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Item 1
  </li>
  <li class="task-list-item">
    <input
      type="checkbox"
      class="task-list-item-checkbox"
      disabled="disabled"
      checked="checked"
    />Callout inline styles
  </li>
  <li class="task-list-item">
    <input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Item 2
  </li>
  <li class="task-list-item">
    <input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Item 3
  </li>
</ul>

We can use these generated classes to style the checkboxes. We’ll remove the default list styles and padding and set up each li as a flex container. Each have two flex items – the checkbox and the text. This ensures that the text doesn’t wrap dowin under the checkbox for multi-line items.

.task-list {
  list-style-type: none;
  padding-left: 0;
}

.task-list-item {
  position: relative;
  display: flex;
  align-content: center;
  padding-left: 0;
}

Next, we’ll remove the default appearance, set a hight and width and nudge the box with some margin so it’s about the same height as lowercase characters and is aligned a tiny bit above the baseline. We’ll also add a border of our own.

.task-list-item-checkbox {
  margin: 0.5em 1em 0 0;
  height: 0.7em;
  width: 0.7em;
  min-width: 0.7em; /* Prevent flex-shrinking */

  -webkit-appearance: none;
  -moz-appearance: none;
  -o-appearance: none;
  appearance: none;
  outline: none;

  border: 1px solid rgba(0, 0, 0, 0.3);
}

Finally, we’ll add a tick (✓) to any that are checked, style it and position it properly within the box.

.task-list-item-checkbox:checked:before {
  content: '\2713';
  position: absolute;
  top: 0.645em;
  font-size: 0.6em;
  font-weight: 600;
}

To make this work properly on iOS, we also need to explicitly set the background and border-radius, and bump the opacity of disabled checkboxes up to 1.

.task-list-item-checkbox {
  // ...
  border-radius: 0px;
  background: transparent;
  //...
}

.task-list-item-checkbox[disabled] {
  opacity: 1;
}

And that just about wraps up styling for lists. I’m sure I’ll revisit some of this when I start to add colour to the site, but for now this is a definite improvement over the defaults.

Website Redesign Part X - Links

Thu, 25 Jun 2020 00:00:00 GMT

Hyperlinks are what makes the web special. They allow us move seamlessley from idea to idea at our own pace. While we tend to read books sequentially, websites are more like choose your own adventure books – hyperlinks let us choose how we experience them. And it’s that way by by default. So links should be pretty prominent on this site. But at the same time, an article peppered with bright blue links is not easy on the eye. Where links are incidental to the text (as many are), they interrupt the flow of reading. I’ve spent a fair bit of time thinking about how I want links to work and I basically have two requirements.

They must get out of the way when reading and not be a distraction.
They should obviously be links for users who are looking for them. This includes differentiating between unvisited and visited links.

Let’s start off by removing styles from hyperlinks that have a class. This gives us a good starting point for styling UI links and also deals niceley with the footnote links that jekyll creates.

a[class] {
  text-decoration: inherit;
  color: inherit;
}

The default clours in most browsers are blue for unvisited links and purple for visited links, so I like the idea of sticking with that since it’s alrreasy well-understood by most users. Rather than colouring the whole word, we might be able to get away with colouring just the underline. This makes the links far less intrusive. we can also pick much less saturated colours than the default.

The hover styles can afford to be a lot bolder and brighter. Something like…

We can achieve this by setting links to inherit their text colour from their parent and styling the underline with text-decoration-color. We’ll also add a subtle transition on hover and force the underline width to 1px on browser that support it.

--color-link-underline: rgba(111, 131, 222, 0.5);
--color-visited-link-underline: rgba(188, 127, 219, 0.5);
--color-active-link-underline: rgb(255, 30, 28);

a:not([class]) {
  color: inherit;
  text-decoration-color: var(--color-link-underline);
  text-decoration-thickness: 1px;
  transition: all 0.25s;

  &:visited {
    text-decoration-color: var(--color-visited-link-underline);
  }

  &:hover,
  &:active {
    text-decoration-color: var(--color-active-link-underline);
    color: var(--color-active-link-text);
  }
}

This feels okay on devices with a pointer. Although the underlines are subtle, if the user isn’t sure it’s a link, they can mouse over and the transation will make it pretty clear. But on touch devices this is impossible, so it feels sensible to make the links a little more ovbious somehow. On mobile devces the text also has a much smaller measure and therefore more multi-line links, whihc looks kinda ugly.

We can alter our code to cremove the underline on touch devices and instead change the text-colour. I’m using a similar blue and purple here, but it’s nececarrily much darker and without an alpha channel. I tried to use a colour that didn’t affect the typographic colour of the text. If you try squinting and looking at the mobile version the links shouldn’t feel lighter or heavier than the rest of the text.

a:not([class]) {
  //...

  @media (pointer: coarse) {
    text-decoration: none;
    color: var(--color-link-text);
  }

  &:visited {
    text-decoration-color: var(--color-visited-link-underline);

    @media (pointer: coarse) {
      color: var(--color-visited-link-text);
    }
  }

  //...
}

Finally, I want to do something about the outline browsers apply when a link is focussed by keyboard. I don’t want to do too much with this for accessibility reasosns, so we’ll just change it from blue to our brand red using the focus visible psutedo-selector. I’ll revisit keyboard navigation once I have a color palette for the site.

a:focus-visible {
  outline: 3px solid var(--color-red-trans50);
}

Website Redesign Part VII - Responsive Typography

Mon, 22 Jun 2020 00:00:00 GMT

Having settled on a typeface for my essays, it’s time to set up some basic typography. In the past, I’ve spent a lot of time building maths-based ype systems with myriad variables and functions and it’s so tempting to go down that route this time and try to create a system that caters to every eventuality. But that would be at odds with my simplicity value, so for the time being I’ll stick to the basics. We’re going to set up a base font size and line height and scale that as the viewport grows. We’ll also add just enough whitespace to create a nice vertical rhythm and create some visual hierachy by styling the headings. Everything else can wait.

Base font-size

We’ll start off by setting the font-size of the HTML element to 100%. This makes sure that 1rem will always represent the default font-size of the device or browser - usually 16px. We’ll use rems and ems to define pretty much every other size in the site, so we’ll also set the body font-size in rems so it’s inherited by other elements.

We also want to reset the heading sizes to 1em. We’ll probably redefine some of these later but I always think it’s a good idea to start with one size for all elements, since it often makes sense to differentiate headings with weight, style or color rather than size. We’re using ems rather than rems here because we want them to scale if we change the font-size on their container.

html {
  font-size: 100%;
}

body {
  font-size: 1rem;
}

h1,
h2,
h3,
h4,
h5 {
  font-size: 1em;
}

Scaling Type Size

We can use the new CSS clamp() function to enable responsive type without the need for a million media queries. This will scale the type from 1rem (16px) to 1.375rems (22px). The middle value is calculated using both viewport units and rems: the vw causes the type to scale with the viewport width and the rems ensure that user-initiated text resizing still works. I arrived at 0.6rem after a bit of experimentation.

.essay {
  font-size: clamp(1rem, calc(0.6rem + 1vw), 1.375rem);
  transition: font-size 0.1s;
}

Hyphens

Enabling hyphenation can make a big difference to readability on small screens, where an uneven right rag can cause very short lines. We can set up a SCSS variable for breakpoints and then use a media query to turn hyphenation off for larger viewports.

$breakpoint-m: 42em;

.essay > p {
  -webkit-hyphens: auto;
  hyphens: auto;

  @media (min-width: $breakpoint-m) {
    -webkit-hyphens: none;
    hyphens: none;
  }
}

Vertical rhythm

The main purpose of a baseline grid is, unsusprisingly, aligning the baselines of text. This makes a huge difference when we have multiple columns of text with differing fonts, sizes and the like.

While this makes a huge difference to the feel of a page, the fluid nature of web pages (and the way line-height works) makes this quite hard to do consistently. We can avoid this problem entirely by only having one column.

But baseline grids can also provide a sense of vertical rhythm – something we can do on the web without too much effort. We just need to work out how high each of our lines is and use multiples of that measurement to space things out vertically. (It can also make a good measurement for horizontal spacing.)

For the time being, we’ll keep our vertical rhythm super simple. First, we’ll remove all top and bottom margins - I’ve chosen to do this in my base stylesheet rather than just for the essays. Then we’ll set up a custom property to hold our base line-height and use that to set the line-height for all the elements in the essay container.

*,
*::before,
*::after {
  margin-top: 0;
  margin-bottom: 0;
}

:root {
  --base-lh: 1.5;
}

.essay > * {
  line-height: var(--base-lh);
}

We can now use this base line-height to set margins on our headings, paragraphs and the like. We can use the lobotomized owl selector to target all elements that have something above them and add a margin equal to our line-height. For now, we’re using ems so the margins will scale with the font-size.

> * + * {
  margin-top: calc(1em * var(--base-lh));
}

We can add top-margin in the same way to other elements. By sticking with top-margin and never using margin-bottom, we have a simpler mental model for how spaces between elements are calculated: we never have to worry about margin collapsing or make a decision on whether to use top or bottom margin.

While we’re here, I also used this tto set some horizintal padding on blockquotes

blockquote {
  border-left: 2px solid rgba(0, 0, 0, 0.2);
  padding-left: calc((1em * var(--base-lh)) - 2px);
  font-style: italic;
  margin-left: 0;
}

Styling Headings

Looking through my articles I dont’t tend to use H1s very often at all, apart from as the article title. This makes sense from a semantic point of view so we can assume that all H1s inside .essay are an article title. I tend to use H2 and H3 fairly often to break my articles into sections, and H4s often appear in logner articles. I rarely, if ever use H5-6.

With this in mind, it makes sense to keep things super-simple. Here’s what I initially settled on…

Aside from H1s, all are set at the same size as the body copy. Five and Six are styled identically in italic with the same weight and margins as paragraphs. Four is set in small-caps with a semibold weight, again with the same margin as paragraphs. Three and Two are both set in bold with a bigger top margin, two being differentiated by being uppercase.

The article title is bigger, and increases is size on larger viewports.

.essay > h1 {
  font-size: 2rem;
  @media (min-width: $breakpoint-m) {
    font-size: 3rem;
  }
  font-weight: 500;
  font-variation-settings: 'opsz' 50;
  line-height: 1.3;
}

.essay > h2 {
  font-weight: bold;
  text-transform: uppercase;
  letter-spacing: 0.15ch;
  margin-top: calc(2em * var(--base-lh));
}

.essay > h3 {
  font-weight: bold;
  margin-top: calc(2em * var(--base-lh));
}

.essay > h4 {
  font-weight: 600;
  text-transform: lowercase;
  font-variant: small-caps;
  letter-spacing: 0.05ch;
}

.essay > h5,
.essay > h6 {
  font-weight: normal;
  font-style: italic;
}

I’ve also turned off styling for any links inside headings by having them inherit their styles from the heading elements.

h1,
h2,
h3,
h4,
h5 {
  a,
  a:visited,
  a:hover,
  a:active {
    color: inherit;
    text-decoration: inherit;
  }
}

I’m generally pretty happy with this, except for one thing. I use level two headings more than any other and because I’ve set them in uppercase I’m missing out on the loveley discretionary ligatures that Literata includes. So I might want to revisit this soon.

Website Redesign Part VIII - Adding some style

Mon, 22 Jun 2020 00:00:00 GMT

The last part focussed on setting up a basic typographic system using margins and heading styles. In this part, I’m going to make a bunch of little tweaks to the typography of these essays. Over the next few months I’ll probably make a whole host of little incremental changes like this.

Old-style Figures & Fractions

Most good typefaces contain two sorts of figures. Lining figures are designed to sit on the baseline and are generally all the same height. They’re great for headings, tables and UI. Old-style figures overhang the baseline and often vary in height. These are great for setting numbers in body copy.

I’m using the default lining figures in most places, but I want to use old-style figures in paragraphs, lists and blockquotes (eg. 1957). I also want to use proper fractions like this → 3/4.

.essay > p,
.essay > ol,
.essay > ul,
.essay > blockquote {
  font-variant-numeric: oldstyle-nums diagonal-fractions;
}

Bold

Where variable fonts are supported, I’m making strong tags a little bolder than normal.

strong {
  font-weight: 600;
  @supports (font-variation-settings: normal) {
    font-weight: 625;
  }
}

Abbreviaions

Abbreviations like HTML nearly always look best rendered in small caps with a little space between the letters, so I’m doing that for any <abbr> elements:

Use small caps and transform the text to lowercase to we don’t get any proper caps mixed in.
Space out the letters a bit (I’m using ch here, which is based on the width of the “0” character).
Use a low optical size and fall back to Literata Caption where variable fonts aren’t supported.
Use a slightly heavier weight than normal - roughly equivilent to Semibold.
Set the cursor to help is it has a title attribute.
Make the dotted underline almost invisible, and position it under the baseline rather than on the baseline.

.essay abbr {
  text-transform: lowercase;
  font-variant: small-caps;
  letter-spacing: 0.05ch;

  font-family: 'Literata Caption', Georgia, 'Times New Roman', serif;
  font-weight: 400;
  font-size: 0.85em;
  @supports (font-variation-settings: normal) {
    font-family: 'Literata Variable', Georgia, 'Times New Roman', serif;
    font-variation-settings: 'opsz' 10;
    font-weight: 410;
  }

  text-decoration-color: rgba(0, 0, 0, 0.15);
  text-underline-position: under;

  &[title] {
    cursor: help;
  }
}

First line & Drop Caps

I’m experimenting with adding drop-cap and small caps for the first line. I’m not yet sure whether I really like this, so will probably revisit later on. I’ve also added hanging punctuation for paragraphs (only supported by Safari at the moment)

.essay > p {
  &:first-of-type::first-line {
    text-transform: lowercase;
    font-variant-caps: small-caps;
    font-weight: 500;
    @supports (font-variation-settings: normal) {
      font-weight: 525;
    }
  }

  &:first-of-type::first-letter {
    text-transform: uppercase;
    float: left;
    font-size: 4em;
    line-height: 1;
    padding-right: 0.5ch;
  }
}

That’s it for now. I’ll cover lists, code blocks and links in future articles.

Website Redesign Part VI - Adding a Typeface for Essays

Sun, 21 Jun 2020 00:00:00 GMT

After much messing about with typefaces, I think I’ve narrowed the choice for essay copy down to two contenders: Literata and Lora. Both feel “bookish” and are designed for long-form reading on screens. Both are open source and available as variable fonts as well as static. Version 3 of Literata not only allows us to vary the weight, but also the optical size. The static version has four optical sizes – each in various weights and italic versions.

The caption variant is designed for small sizes (around 7pt), the regular variant for body copy and the deck and display variants are meant for headings. The variable version gives me pretty fine-grained control over this.

Since I’m not sure which of these two typefaces I prefer, I’ve decided to bring both of them into the website and switch them out regularly as I’m working to see if one starts to grow on me.

Although I initially wanted to serve fonts via Google Fonts, I’ve changed my mind. One of my technical principles is as few dependancies as possible, and these are both open source I can host the myself. I was finally tipped into this decision because Google Fonts doesn’t have the latest version of literate available.

Building the fonts

I’ve never had to build fonts from source before, but after much yak shaving to update my python install and various home-brew packages I was able to run the three build scripts from the Literata repo. It toook a while to work out what they do, but essentially:

build-static.sh builds a bunch of TTF font files from source using the fontmake utility. This produces a lot of files – one for each weight/style/optical-size combination.
build-var.sh does the same, but for the variable fonts. It only produces two TTFs: roman and italic.
build-woff.sh takes the TTFs we just built and makes woff and woff2 versions using the sfnt2woff and woff2_compress utilities.

Since the Lora repo already includes TFF files, I just tweaked build-woff.sh a bit and used it to make corresponding woff/woff2 files with the same folder structure as Literata.

After renaming the wolf and woff2 versions of the variable fonts to remove the brackets, I ended up with this in the fonts directory of this site…

The whole thing comes in at a whopping 28MB, but that’s okay because I’m not actually gonna use most of these in production. I just want them to play with for the moment.

@font-face Declarations

I borrowed the Literata font-face declarations from Jason Pamental’s amazing Moby Dick project and added some similar ones for Lora. I’m pretty sure I’m gonna borrow a lot more from that project over the next few months. They generally follow this format:

@font-face {
  font-family: 'Literata Caption';
  font-style: italic;
  font-weight: 600;
  src:
    url('../fonts/literata/woff2/Literata-7ptSemiBoldItalic.woff2') format('woff2'),
    url('../fonts/literata/woff/Literata-7ptSemiBoldItalic.woff') format('woff');
  font-display: swap;
}

It’s been a long time since I actually looked at a @font-face declaration, so if you need a reminder too:

We’re writing a declaration for Literata-7ptSemiBoldItalic. This is the caption-sized version, in Semibold italic.
The first three lines specify when this font file should be used. In this case when we set font-family: 'Literata Caption' with a weight of 600 and an italic font-style.
The src attribute specifies the path to the woff2 version first and falls back to the woff version if that’s not supported (woff 2 offers much better compression than woff 1). Since woff is widely supported we’re not including any other fallbacks.
font-display tells the browser how to handle font loading. In this case, the browser will render the text in a fallback and then our font in once it’s loaded.

The variable font declarations look much the same, but include two values for font-weight: the minimum and maximum at which it should be used.

Using the fonts

Our current CSS sets the font-family for essays using a custom property.

.essay {
  font-family: var(--font-essay);
}

As the design evolves, we’ll definitely end up with a more complex system for this but for now we can just update the variable to use Literata. We can also tell browsers that support variable fonts to load that instead of the static version.

:root {
  --font-essay: 'Literata', Georgia, 'Times New Roman', serif;

  @supports (font-variation-settings: normal) {
    --font-essay: 'Literata Variable', Georgia, 'Times New Roman', serif;
  }
}

I’d like to provide a more robust fallback stack (see this issue) but for now, we’ll just go to Georgia and TNR.

Some basic Open Type Features

Literata includes some lovely discretionary ligatures, but we don’t want them in the body copy. I’ve already set font-variant-ligatures: common-ligatures; on the body in my base stylesheet, but we’ll turn on discretionary ligatures for headings across the whole site:

h1,
h2,
h3,
h4,
h5 {
  font-variant-ligatures: common-ligatures discretionary-ligatures;
}

So where are we at?

I’ll see which of these two feels best as I work on the site over the next few weeks.

Reflection on Learning

One of my goals for this project was my own learning, and after some reflection on that I’ve learned a fair bit during this wanter into web typography…

I finally read The Elements of Typographic Style cover-to-cover.
I’ve learned a lot about type just by really looking at a bunch of different faces.
I’ve learned a bit about how digital fonts are made and the tools used to build them.
I’ve started to get excited about opentype features in CSS.

I’ve also re-learned that it’s easy to get blocked by indecision on a personal project like this. I could have wasted months trying to find the perfect article typeface and still not been happy with it. As with most things, any decision is better than no decision. Especially when it’s reversible.

Website Redesign Part V - Choosing a Typeface for Essays

Sat, 20 Jun 2020 00:00:00 GMT

I love typography, but I’m not that good at it. One day I’ll take a typography course at a a design school, but in the meantime I need to choose some typefaces for this website. I’m fairly confident I’ll need two rather different typefaces in the end. A essay face for setting longer-form writing and a UI face for everything else. I like the idea of using a very modernist face for the UI and something more old-fasioned and bookish for the essays. It might be hard to make this work but it seems to chime will with my personality – I’ve always had a tendancy to mix super-modern with traditional oldy-worldy. Trainers and Tweeds, if you will.

I’ll explore this in more detail in a future article, but for the time-being let’s revisit the four core values I decided on in Part I: Simple, Beautiful, Authentic and Content-first. Choosing and pairing typefaces is hard, so to keep things simple we’ll start by looking for one. And that last value makes a strong case for starting with the content.

What do I need from an Essay Typeface

The most obious requirement is that it’s very readable. And in particular, on screens. It needs to get out of the way and put the content first. It also needs to work well in dark mode, which probably rules out faces with very high stroke contrast (and therefore thin stokes). And to keep things simple, it should also work for headings, quotes, captions and the like –I’d rather not use a third face for this.

As far as feel goes, I’m going for bookish but definitely of the digital world. This probably means a serif, but maybe not a really traditional one.

So I’m going to start by looking for faces that are digital natives (ie not redrawings of print faces), which have been designed specifically for readability on the screen. There are a few technical constraints to think about first, though.

Technical Constrains & Features

It must be open source. While I have a subscription to Adobe Fonts I don’t want this project to depend on a paid service. If I can find something that’s hosted on Google Fonts so much the better. Because simplicity.

I’d prefer a variable font. Mostly because they’re new and shiny and fun to play with, but also because it’s likely to reduce total page weight. If I go with a variable font, it also needs to have a static version – not all browsers properly support variable fonts yet.

I’ll need a good selection of weights in both roman and italic. Probably 200 (light), 400 (normal), 700 (bold) as a minimum. I’ll also want support for the following opentype features¹:

Proper small caps
Both Old-style and and Lining figures
Nice default and discretionary ligatures
Fractions

It would be nice to have a proper superscript for footnotes, but this is hardly crucial.

Checklists

I’ve bubbled all of that down into a couple of checklists to help me evaluate fonts. On reflection, none of the items are really mandatory – it’s important I keep an open mind while I’m exploring. But they’re good starter to help narrow down the field.

Technical Features

Open source?
Available on Google Fonts?
Variable Font? (with static version as fallback?)
Wights at least: light (200), normal (400) and bold (700) in italic and bold.
Proper Small Caps
Old-style and lining figures
Nice ligatures (including discretionary)
Proper Fractions
Other OpenType features that might be fun/useful?

Style

The Shortlist

After a lot of exploration, I’ve settled on five candidates. None hit all the criteria in the checklists, but a few get pretty close. And I like them all.

Spectral

(Google font page)

Specral was designed in 2017 as a screen-first typeface. This article goes into a lot more detail.

Spectral is a new and versatile serif face available in seven weights of roman and italic, with small caps. Intended primarily for text-rich, screen-first environments and long-form reading

Over the past decade, the amount of attention given to readability studies by typeface designers has yielded either bland and conservative results, or overwrought “solutions.” This is more pronounced in screen typefaces than those made for print media, where common pitfalls include overly simplified shapes, “friendly” letters, and facile tricks like unnecessarily upright italics.

In response, Spectral takes an unambiguous stance: Screen typefaces should not look like caricatures of themselves. They should instead be functional text designs that stay interesting enough to convey the many voices that contemporary users need.

At first glance, this seems like it might be a great choice, but after some experimentation the very high stroke contrast makes it feel a bit too bookish. It’s a bit too spindly, somehow. It also doesn’t work that well on dark backgrounds at small sizes.

If I was setting a book on the web, I’d definitely consider this though.

Lora

(Google font page)

Lora is a well-balanced contemporary serif with roots in calligraphy. It is a text typeface with moderate contrast well suited for body text.

A paragraph set in Lora will make a memorable appearance because of its brushed curves in contrast with driving serifs. The overall typographic voice of Lora perfectly conveys the mood of a modern-day story, or an art essay.

Technically Lora is optimised for screen appearance, and works equally well in print.

Lora was designed by Olga Karpushina in 2011. It’s definitely the least unusual of the five, though the fairly upright italic is beuatiful. This is definitely one that would get out of the way and put the content first.

Alegreya

(Google font page)

Alegreya is a typeface originally intended for literature. Among its crowning characteristics, it conveys a dynamic and varied rhythm which facilitates the reading of long texts. Also, it provides freshness to the page while referring to the calligraphic letter, not as a literal interpretation, but rather in a contemporary typographic language.

The italic has just as much care and attention to detail in the design as the roman. The bold weights are strong, and the Black weights are really experimental for the genre. There is also a Small Caps sister family.

Not only does Alegreya provide great performance, but also achieves a strong and harmonious text by means of elements designed in an atmosphere of diversity.

I love the fact that Alegreya has a small caps variant and is part of a super family that includes a sans-serif version - I was wondering if I could use the sans version for UI copy. But much like Spectral, it almost feels too caligraphic and oldy-worldy-bookish.

Literata

(Google font page)

Literata is probably one of my favourites. It feels right for the job, somehow. It’s got a huge array of varients plus a variable version and some lovely ligatures. It was commissioned by Google and designed by TypeTogether in 2015 and is the default font family in Google Play Books. I’m not sure I like the idea of using a face that so many folks will associate with Google, but as far as versitility and reading experience goes, this is definitely on the shortlist.

Bitter

(Google font page)

Motivated by my love for the pixel I designed Bitter. A “contemporary” slab serif typeface for text, it is specially designed for comfortably reading on any computer or device. The robust design started from the austerity of the pixel grid, based on rational rather than emotional principles. It combines the large x-heights and legibility of the humanistic tradition with subtle characteristics in the characters that inject a certain rhythm to flowing texts.

Bitter has little variation in stroke weight and the Regular is thicker than a normal ‘Regular’ style for print design. This generates an intense color in paragraphs, accentuated by the serifs that are as thick as strokes with square terminals.

This also scores well when it comes to readability, but the fact it’s slab serifs and very dark color make it feel a bit too unrefined for use here. It’s still on the shortlist though.

Here’s a good overview of CSS opentype features. ↩

Website Redesign Part III - A Base to Start From

Tue, 07 Apr 2020 00:00:00 GMT

I’m trying to keep the CSS as minimal as possible here, but I do want a decent blank slate to work from. So I’ve normalised browser styles with normalize.css and set up some of my own base styles.

Reset some basic styles to the way I like them.
Set up some variables and use them for base colours and typography.
Remove styles from all lists that have a class - they’re probably part of the UI, not the content.
Remove styles from links that have a class - same reason.
Set default link styles for body copy.
Remove all animations and transitions for people that prefer not to see them.

I’m sure these will change over time, but here they are for now…

A starting point for article typography

Since I’m writing on this site now, there’ll be a lot more written content. My Content-first value means I should probably start with that, while my Simplicity value means I should probably ignore layout and start by making the article copy as beautiful and readable as I can.

So taking a leaf out of Frank Chimero’s book, I’m starting with a very very simple set of styles for my articles.

I’ll focus in on this soon but until I choose a better typeface, --font-copy is set to Georgia. Like Frank, I still like it.

Website Redesign Part IV - Pages and URLs

Tue, 07 Apr 2020 00:00:00 GMT

I bought this domain specifically so I could have cool URLs like danny.is/doingsomething, so definitely want to use certain URLs, regardless of content. These provide a good starting point for deciding what pages I might want.

danny.is

The homepage, obviously. Since the last redesign this has just shown a list of links to other pages and external services, but I’ll probably change that a bit with this redesign.

danny.is/about

A few paragraphs about me. Perhaps some other stuff.

danny.is/now

A very simple description of what I’m doing at the moment. Inspired by this.

danny.is/writing

An index of my writing. This will definitely include my writing on this site, but I might also include stuff I write elsewhere.

danny.is/reading

Stuff I’m reading. Historically, this has been a big list of links pulled from Pocket and Medium. I want to keep that, but might also include books I’m reading, or recommend.

danny.is/cv

A PDF of my CV.

danny.is/using

Forwards to a Notion page detailing the software and hardware I use. I’m sticking with Notion for the moment because I already have much of this written.

danny.is/meeting

Forwards to a notion page where you can book a meeting with me. I’ve been sharing the full notion link for about a year now, and it’s just occurred to me that setting up this forward makes a lot of sense. Again, I’m sticking with notion because I already have it set up.

Other URLs

I’ve also set up forwards for LinkedIn and youtube, since I find it hard to remember their URLs:

danny.is/linkedin → My LinkedIn profile
danny.is/youtube → My Youtube channel

It seems likely that I’ll also want two new pages…

danny.is/lookingforwork

A “Hire me” page which is only live when I’m actively looking for work.

danny.is/coaching

A page detailing my coaching work. I expect this will be the only page where I care about “marketing”.

Pages I need to design

Ignoring the forwards and the now page, that’s eight pages I need to consider when it comes to design.

Homepage
About
Writing (index)
Writing (article)
Reading
Looking for Work
Coaching
404

There’s a part of me that wants to dive into the design of these pages right away, but I’m resisting the urge. Making the writing that’s already here useable is far more important. Keep it simple, Danny.

Website Redesign Part II - Principles, Goals and Stuff to Keep

Tue, 17 Mar 2020 00:00:00 GMT

Until now, every time I’ve redesigned this website it’s been because I didn’t like how it looked. Every few years, I’ve looked at it and felt like it doesn’t adequately represent me.

When I started this redesign process, I fully expected to feel the same way. But having spent a bunch of time staring at it, I think I still like a lot of what I have.

More accurately, I still really like these two pages…

When I designed them back in 2016 I was going for a modern “Swiss” influenced kinda vibe. I think I want to keep that.

But let’s take a step back for a second and think about my goals.

Goals of this site

First and foremost, it’s a personal expression of me. It’s a place for me to have fun: both with my writing and with design & CSS. So it’s okay if it’s a bit goofy or stuff is a bit broken sometimes.

But it also represents me professionally.

Thankfully, in both cases the primary goal remains the same. To help the reader understand me – Danny.

If I put my UX hat on for a minute, there is a Job To Be Done that I should consider. A subset of visitors to this site are trying to find out if I’m the right person to help them with something.

Similarly – with my marketing and I-need-money-to-eat hat on – there is another subset of visitors that need my help; but neither of us know it yet.

The last thing I want is for my personal site to be some sort of super-optimised landing page for Danny The Professional®. Because that’s no fun. And it’s not at all an expression of me. But I do need to consider these special use cases a bit.

Of course, there are also the random folk who come here to read the stuff I write. They probably just wanna read in peace.

So if I think in terms of actors and their goals:

Danny
- Express himself freely and without constraint.
- Have fun. With writing, design and code.
- Connect with people he can help, or who can help him.
Interested reader
- Read Danny’s words in peace.
- (Perhaps) be notified when Danny writes some new words.
Person checking Danny out
- Find out if Danny is the right person to help them.
- Contact Danny.

This feels like a good set of goals to start with. But they come in a strict order of priority: Danny → Interested Reader → Person Checking Danny Out. This is my personal website, after all.

So here’s a rule I’m gonna try to stick to:

Given a choice between what I want to do and what I feel I should do because [reasons], always choose the former.

Goals of this redesign

As I said in Part I, I’m doing this primarily for two reasons:

I want a simpler, more technology-agnostic website.
I want to write here, not on Medium.

Combined with the website goals up there ☝️, I think I’m trying to achieve the following:

Represent myself more authentically.
Simplify my own mental model for who I am and what I do, as expressed through this site.
Make things more obvious and useful to readers.
Put my writing at the front, and make it beautiful.
Provide somewhere for folks to find out about my work, and how I might be able help them.

I suspect (2) and (3) mean better content organisation and hierarchy, along with some self-imposed constraints. (4) probably means better typography and more focus on the tiny details. As for (5) – that’s probably just a page of its own.

The first one is interesting though. I said earlier that I like the current design. For the first time ever it still feels authentic now that Redesign Time has rolled up. And so it does. At least what there is of it.

And perhaps that’s the problem. My current site is too sparse. Too sanitised. Sure, it has some wacky angles and stuff. But it has no substance.

It also feels a bit cold and unloved. Like a well-machined tool that rarely gets used.

I’d much rather it felt like a hand-made tool that’s used and loved every day. It’ll probably have more dents and scratches, but it will feel much more like home.

Representing Danny more authentically

I recently asked some friends to describe me using as many single words/short phrases as they wanted. The list so far has been a great prompt for reflection and has led me to a fair few blind spots, but I’m still waiting for a lot of folks to come back to me.

I’m hoping that this will help identify some words that I feel authentically represent me.

So where are we at?

Besides the fact that I like my current website, we’ve identified three main actors and their goals. We’ve also established five initial goals for this redesign, and expanded on the most important of them.

Back in Part I I listed four values that felt right as guides for this project.

Simple
Beautiful
Authentic
Content-first

They still feel right to me. And they now have bit more flesh on them.

What about my current website?

Before wrapping this up, I want to take a look at my current website with all this thinking in the back of my mind. I particularly want to look at the two pages I like – the homepage and the 404. Here are some unedited thoughts on them:

They are simple. ✅
They put the content first – even though there is hardly any of it. ✅
There should be more content.
I think the 404 page is beautiful. I love how the colour, type and layout interact. ✅
The homepage is less beautiful. Futura looks pretty bad at very large sizes and the whole thing feels slightly unpolished somehow. It lacks attention to the little details. Inauthentic.
Futura is a lazy choice of typeface - I use it everywhere.
The 404 page feels like an authentic representation of me¹. The homepage less so. This might have more to do with the content than the deign. I talk a lot and am generally friendly, and it feels a bit too minimalist and impersonal. It’s somehow not goofy enough, where the 404 page is. At least the palette feels warm ad cosy.
I’m going for a kinda Bauhaus/Swiss vibe but there’s no grid. I’m a massive nerd for orderly systems and grids, so this feels both inauthentic and like a missed opportunity to create some beauty through mathematics.

Until next time.

Yes I know, “Not Found”. 🙃 ↩

Website Redesign Part I - The Tech

Sat, 14 Mar 2020 00:00:00 GMT

Over the years, this website has taken many forms. Initially, it was a Wordpress blog. Then is was a hand-rolled Sinatra app that rendered markdown pages. More recently I’ve blogged on Medium and at the time of writing, my website is a much simpler Sinatra app.

A few months ago I had an ongoing problem with medium which lasted about three months. I got a new Monzo card and medium couldn’t charge it. Although none of my articles were behind the paywall, it did mean that I couldn’t read other people’s paywalled articles. And even though I was happy to pay, I couldn’t. Eventually, after many many emails between me, Monzo and Medium, I involved Medium’s payment processor Stipe. Turns out that the problem was some bad data on their end. We resolved it, but only because I knew about stripe.

This whole experience left a bad taste in my mouth, and like a lot of other people it feels like time to move the canonical version of my writing onto a platform that I own… my own website.

At the same time, I’ve also become frustrated with my website. Considering what it does, it’s most definitely over-engineered. It’s not fun to play with any more, and I seem to spend most of my time on it updating dependancies. I also have to pay Heroku to keep it running.

Time to simplify things, then. I need a static site.

Why a static site?

If my site is just HTML and CSS then it’s easy to change, even if I’ve not touched it in years. There are no complex mental models to remember, no dependancies to manage, no security vulnerabilities to patch. I can also deploy it anywhere. I’m not reliant on any specific third parties. Static sites are also web scale by default when hosted in the right place.

So that’s my starting point… plain old HTML and CSS, deployed to Github Pages. When I want to write a new article I just make an HTML page. Simple.

But I also want to enjoy writing articles, which probably means writing in markdown.

So a static site generator is the obvious choice. All the cool kids are using Gatsby and Hugo, but after spending some time with both I think Jekyll is the best option for me. It’s simple, is battle-tested and is very very stable.

Before going any further with the tech, I need some values and principles to guide my decisions.

Values

After some time with a pen and paper, these seem appropriate:

Simple
Beautiful
Authentic
Content-first

Engineering Principles

Based on these values, I’ve pulled out some principles to guide my decisions on tech stack:

As few dependencies as possible (both build-time and run-time dependancies).
Use defaults wherever possible.
Write as little code as possible.
Do not over-abstract. Avoid fallbacks, polyfills and hacks.
Bake accessibility in.

I’ll come back to these regularly.

Jekyll Plugins

It’s tempting to install a whole bunch of plugins – there are some great ones out there. But every plugin is a build-time dependancy, so I’ve settled on just three.

Optional Front Matter. This makes the front-matter optional, obviously. I want it so that my HTML pages don’t need any front matter.
SEO Tag. This adds a bunch of SEO-related meta tags in a pretty intelligent way.
Redirect From. This lets me set up redirects in a super-intuitive way. I can crate an empty page or post, specify the redirect in the front matter and be done with it.

But what about dynamic stuff?

My current website has some dynamic stuff. The only bits I still care about are my reading list and highlights. My medium highlights are pulled in via their private API and cached in Redis.

My pocket items and medium recommendations work a bit differently. When I clap for an article on medium or archive one in pocket IFTTT sends a request to an endpoint which stores the details in a Postgres database which the Sinatra app can access.

On reflection, I don’t care about the highlights right now.

But I definitely want to retain the likes from Pocket and Medium. I don’t want to maintain a Postgres database though.

Enter Airtable. I can have IFTTT create a record in Airtable whenever I clap for a medium article or archive a pocket item.

Although this means I’m dependant on Airtable for this part of my website, I’m okay with that because it’s not a core part of my site: if airtable goes down or kill my account then 🤷‍♂️. The advantages well outweigh the overhead of managing my own server and database. Also…

It’s easy to pipe data into Airtable from all sorts of places.
It’s easy to edit data in airtable, especially because I use it a bunch anyway.
It has a very nice API.

There is one problem, though. For my javascript to access this data it needs my Airtable API key. I can’t just bung that in my code because then everyone would have it. This is something Netlify’s lambda functions are great at: they can act as an intermediate layer between my client-side javascript and the Airtable API.

Netlify also makes a lot of sense for hosting: it has some bells and whistles Github Pages lacks.

So here’s where we’re at so far…

Core Stuff

Just HTML, CSS and Markdown.
Jekyll (with a couple of plugins).
Netlify for hosting.

Reading List Stuff

Airtable - data store.
Netlify Functions - accessing Airtable.
IFTTT - piping stuff into Airtable from elsewhere.

What about the writing experience?

For the most part, I’m happy to write locally in iA Writer or VSCode. For writing on-the-go, Forestry seems like the best option. I’d dearly love to find a git-based-jekyll-compatible editor that works like Ghost or Medium, but that can wait.

With these decisions made, it took a surprisingly small amount of time to get all this wired up. Less than two hours. That’s the value of simplicity, I suppose.

Business Process & Tooling

Thu, 05 Mar 2020 00:00:00 GMT

Little Thing — Mocking External Services on Ruby

Wed, 04 Mar 2020 00:00:00 GMT

Breaking Down Problems: It’s hard when you’re learning to code

Wed, 14 Nov 2018 00:00:00 GMT

Little Thing — Value Objects in Ruby

Mon, 05 Nov 2018 00:00:00 GMT

Little Thing #2 — Speeding up ZSH

Thu, 09 Aug 2018 00:00:00 GMT

Little Thing #1 — How do RSpec Matchers Work?

Thu, 12 Apr 2018 00:00:00 GMT

Little Things

Mon, 02 Apr 2018 00:00:00 GMT

Synchronising Git Merges with Slack

Tue, 19 Dec 2017 00:00:00 GMT

The Definition of Done: What does “done” actually mean?

Tue, 19 Dec 2017 00:00:00 GMT

Add Starred Slack Messages to Things 3

Sun, 26 Nov 2017 00:00:00 GMT

Where are the good Mobile Networks?

Mon, 19 Jun 2017 00:00:00 GMT

The Definition of Done: What does "done" actually mean?

Mon, 19 Jun 2017 00:00:00 GMT

Scrum defines the definition of done in pretty simple terms: it’s the acceptance criteria that are common to every single user story. For scrum teams, it’s really important to have a solid definition of what “done” means. They work in sprints, and need some way of deciding whether a user story is actually finished. It’s no good ending a sprint with a user story that meets all its acceptance criteria, but had no code review, hasn’t been tested and isn’t deployable. Such a story is clearly not done. Scrum teams solve this by strictly defining “done”. In this case, in addition to meeting the acceptance criteria, the story must also:

Have had a code review.
Have been tested.
Be immediately deployable.

If this isn’t the case at the end of the sprint then it isn’t done - we can’t count it’s story points towards the sprint velocity and it needs to go on the backlog for the next sprint planning session.

What does “done” actually mean, though?

Is a new feature “done” when it’s in production and being used by customers? It might be. Equally, it might not. Have we published the changelog? Have we emailed our customers to tell them about the feature?

When is a technical improvement or refactoring “done”? We certainly don’t want to email our customers about it, and we probably don’t want to add it to the changelog.

The definition of “done” depends on the task.

Some teams get around this problem by having multiple definitions of “done” - one for bugfixes, another for features, another for technical tasks, and so on.

At CharlieHR, this seemed overly complex. We don’t use scrum, and we don’t work in iterations. But we still need a way to remind ourselves of the stuff that should be done before a task is considered finished. So we invented a checklist.

Our DoD at Charlie

We use two definitions. The first is ready to merge. Everything in this checklist needs to be ticked off before the pull request is merged to the master branch. The second is actually done. Everything in this checklist must be ticked off before the card is moved to the Done column on our task boards.

It’s worth noting that these rules apply to every single work item that goes through our task boards, so long as it involves code. Whether it’s a large user story with multiple dependencies or a tiny bugfix, the person doing the work is expected to run through these checklists.

That doesn’t mean that everything on the checklists has to be ticked off for every work item, though - a tiny technical improvement is unlikely to need a marketing email written about it, for example. It does mean that everything in the checklist must be considered for every work item. We trust our engineers to use their judgement.

While you’re reading the DoD below, bear in mind…

We use Trello for our task boards. Most teams have columns for backlog, next up, in progress and done. New features and user stories are represented by trello cards on a team backlog.
Technical improvements and exceptions begin life as GitHub issues. These get a trello card on the backlog when they are assigned to or picked up by a team. Bugs live in Sifter, and get a trello card when they’re assigned to a team.
The order in which the items below are considered is irrelevant, so long as they have all been considered.

I’ve made notes in italics, since some of the items need a bit of explanation.

Checklist 1: Ready to Merge

Kickoff done and requirements clear. Kickoff Document stored on Drive. This is where we define our acceptance criteria and the scope of a new feature. Most non-trivial user stories require this, and the kickoff for an epic may spawn multiple, smaller, inter-dependant user stories. Bugfixes don’t normally need a kickoff: it’s down to the product manager and engineers to decide whether a work item needs one. The kickoff document is just the record of the discussion, and contains sufficient acceptance criteria to get the thing out.
Implementation Plan written and reviewed. This is something we’re trying out. For non-trivial work items, engineers discuss and plan the technical solution. This usually involves whiteboarding and scribbling on bits of paper. The implementation plan is a summary of that thinking and is available for engineers from other teams to review. We’re hoping this will help catch architectural and system design problems early. For technical improvements, this discussion has usually happened on the associated github issue already.
DPIA Form Completed. Do we need to do a Data Protection Impact Assessment?
Card on Trello, properly labelled, sized and PR/Issue linked (mandatory). Before a trello card is picked up it must be labeled, have a T-Shirt size and have any associated stuff (kickoff doc, implementation plan, github issue, sifter issue etc) attached to it. Once a pull request is open, this (or these) should be attached too.
Pull Request open and properly labelled (mandatory). We open a PR after the first commit to a branch. Early comments on the PR save time and help share knowledge between teams.
Acceptance criteria met. Obviously. If changes to the requirements have been agreed with the product manager, have they been noted on the kickoff document or trello card?
Unit tests written.
Functional specs written.
Documentation folder reviewed for any changes/additions. We have a directory containing markdown files that describe the design patterns and conventions we use.
Environment variables documented, added to secrets manager and present in staging & production environments.
Analytics considered. Do we need to track user behaviour, and how should that be reported to our analytics tools. For larger work items, this is usually specified in the the kickoff doc.
“What’s New” section updated. If this is a new feature, we may want to tell our users about it.
l18n reviewed. All our copy (including microcopy) should live in locale files.
Security & Data Protection Review (mandatory). We take security seriously. Have we made a deliberate and methodical check that this doesn’t introduce any obvious security or data protection issues. This is particularly important for small bugfixes, since they may not have had detailed planning.
Code Review from at least one other (mandatory). We strictly enforce this with our GitHub settings.
CodeClimate clear of errors. As well as tracking our test coverage, we run static analysis tools like rubocop and ESLint against out changes. We’re still tweaking the rules for these tools to suit our in-house style.
Feature Branch green on CI (mandatory). We also enforce this. You cannot merge to master with a red build on your feature branch.

Checklist 2: Actually Done

Merged to master and feature branch deleted (mandatory). The master branch is automatically deployed to our staging environment. I wrote about our merge process earlier.
Related GitHub Issues closed or updated.
Sifter, Appsignal, and #tech-support issues closed 🏁. We have a slack channel where people can raise technical issues. If a work item resolves or relates to one of these, it should be marked. This mostly applies to tiny bugfixes. Resolved bugs and exceptions should be closed in Sifter and Appsignal, respectively.
Manually tested on staging environment (mandatory). We don’t have dedicated QA people, so engineers and product managers conduct acceptance and exploratory tests. For work items that carry significant business or technical risk, we’ll draft in people from across the company to help.
Deployed to production with no obvious errors/exceptions (mandatory). Once a PR is deployed, we expect our engineers to keep an eye on the slack channel that shows our exceptions. If the deploy causes a flurry of them, it should either be rolled back and fixed or they should be addressed in a new PR before the work item can be considered done.
Release email sent. We send a company-wide email for all non-trivial releases.
Marketing document updated. If the work item is a new feature or important bugfix, it’s recorded in a spreadsheet. The marketing team refer to this when sending updates to our users.
Usage metrics checked/set up. Have we checked that data is coming through correctly? Do we need to update any formulas or one of our Geckoboard dashboards?
Help pages updated. If we’ve added a feature, changed the way something works or updated the UI, we might need to update our user guides, help documentation and canned responses in intercom.
FINALLY, card moved to “done” on trello (mandatory).

Mandatory Items

You’ll notice that some of the items are marked mandatory. Those must be done for every single work item. No exceptions. For a scrum purist, these are the only things that should appear in a Definition of Done. For us (right now), they are probably the least useful items on the list - they’re all important enough that we’d remember to do them even if we didn’t have a checklist!

At the moment, we’re deliberately keeping our mandatory items to a minimum, though we have discussed making more stuff mandatory. As we continue to evolve our process, I expect we’ll add items to support our current engineering goals. If we were focussed on improving our unit test coverage, we might include an item that says “all new models and POROs must have an associated unit test”. If we were focussed on improving the quality of our codebase, we might insist that “every pull request must improve the CodeClimate quality rating”. We might even decide to make proof of business value a prerequisite for “done”.

Currently though, we are focussed on building an awesome product, and while most pull requests include unit tests and quality improvements, it doesn’t make sense to mandate that just now. Our “Definition of Done” is designed to help us work better and faster, and will change and evolve alongside our business goals.

Six awesome services I discovered last year

Thu, 18 May 2017 00:00:00 GMT

DigitalOcean, DNSimple and Terraform: A very short introduction.

Mon, 24 Oct 2016 00:00:00 GMT

Agile Adoption Patterns

Thu, 30 Jun 2016 00:00:00 GMT

Good Slide Design

Sat, 23 Apr 2016 00:00:00 GMT

Slack for Enterprise

Thu, 10 Mar 2016 00:00:00 GMT

A Standard Software Toolset for Business?

Sun, 06 Mar 2016 00:00:00 GMT

Finding a Good Colour Palette through Exploration

Wed, 02 Mar 2016 00:00:00 GMT

Why do I teach?

Thu, 25 Feb 2016 00:00:00 GMT

Automating and Outsourcing

Sat, 20 Feb 2016 00:00:00 GMT

Collaborating on a Project

Mon, 04 Jan 2016 00:00:00 GMT

Effective Meetings

Fri, 18 Dec 2015 00:00:00 GMT

My Students have Forgotten How to be Curious

Tue, 03 Nov 2015 00:00:00 GMT

Evaluating Training and Learning

Mon, 26 Oct 2015 00:00:00 GMT

Getting Things Done

Sat, 29 Aug 2015 00:00:00 GMT

The Psychoactive Substances Bill 2015

Sat, 25 Jul 2015 00:00:00 GMT

The Changing Face of Software Testing

Wed, 22 Jul 2015 00:00:00 GMT

Delivering Business Value with Kanban and Validated Learning

Tue, 17 Mar 2015 00:00:00 GMT

Blogging with Evernote and Ruby

Thu, 26 Feb 2015 00:00:00 GMT

Replacing Bash with ZSH on OSX

Thu, 26 Feb 2015 00:00:00 GMT

Agile Feedback Loops

Tue, 24 Feb 2015 00:00:00 GMT

Writing Testable Code

Tue, 24 Feb 2015 00:00:00 GMT

On Sass and Other CSS Preprocessors

Sun, 04 May 2014 00:00:00 GMT

Controlling the Rag with Redcarpet

Sun, 04 May 2014 00:00:00 GMT

Good typography is about the accumulation of small improvements. As Mark Boulton puts it:

“Good typographic design — on the web, in print; anywhere, in fact — relies on small, measurable improvements across an entire body of work”

I’ve implemented several typographic improvements in my Ruby-based website using a custom Redcarpet renderer that automatically fixes common typography issues.

The Problems We’re Solving

Orphans - Single words hanging alone on the last line of a paragraph
Short phrase breaks - Emphasized phrases breaking across lines
Awkward line breaks - Lines breaking after prepositions, dashes, or short words

Custom Redcarpet Renderer

Here’s how I implemented these fixes:

Preventing Orphans

def paragraph(text)
  # Replace the space between the last two words with a non-breaking space
  text.gsub!(/\s+(\S+)\s*$/, '&nbsp;\1')
  "<p>#{text}</p>"
end

Keeping Short Phrases Together

def do_not_break_string(text)
  # Keep short emphasized phrases together
  text.gsub!(/<(em|strong)>([^<]{1,15})<\/(em|strong)>/) do |match|
    match.gsub(' ', '&nbsp;')
  end
  text
end

Preventing Breaks After Short Words

def avoid_breaking_after_short_words(text)
  # Complex regex to identify words that shouldn't be broken
  text.gsub!(/(\s)(a|an|and|as|at|but|by|en|for|if|in|of|on|or|the|to|vs?\.?|via)(\s)/i) do |match|
    "#{$1}#{$2}&nbsp;"
  end
  text
end

The Results

These small improvements compound to create noticeably better text rendering:

Fewer orphans - Paragraphs end more naturally
Better emphasis - Short emphasized phrases stay together
Smoother reading - Fewer awkward line breaks interrupt the flow

Implementation Details

The custom renderer processes Markdown content before it’s converted to HTML, applying these typographic rules automatically. This means I can write naturally in Markdown while getting professionally typeset results.

Typography Principles

The key insight is that good typography happens at the micro level. Each individual improvement might seem small, but together they create text that’s:

More readable - Fewer distractions from poor line breaks
More professional - Attention to typographic detail shows craftsmanship
More accessible - Better text flow helps all readers

Conclusion

Controlling the rag (the uneven right edge of left-aligned text) and preventing orphans are foundational typography skills. By automating these improvements in my Redcarpet renderer, I ensure consistently good typography across all my content.

These techniques work especially well on the web, where we have tools like non-breaking spaces to fine-tune text rendering without sacrificing the flexibility of HTML and CSS.

A Pretty Readability Archive with Ruby and CSS

Sun, 20 Apr 2014 00:00:00 GMT

I’ve always found it interesting to see what other people read. Not just the things that they share on twitter, but the articles they read on a daily basis.

I decided to build a web application to display my Readability bookmarks using Ruby, Sinatra, and CSS transitions to create an interactive card-based layout.

The Technical Implementation

The application follows these key steps:

Environment variable setup - Secure authentication credential storage
Readit gem integration - Ruby library for the Readability API
XAuth authentication - Secure API authentication
Bookmark fetching - Retrieving archived articles
Interactive card display - CSS 3D transforms for flippable cards

API Integration

Using the Readit gem, I configured the Readability API connection:

# Configure the Readit API
Readit.configure do |config|
  config.consumer_key = ENV['READABILITY_KEY']
  config.consumer_secret = ENV['READABILITY_SECRET']
end

# Authenticate via XAuth
client = Readit::Client.new(
  oauth_token: ENV['READABILITY_TOKEN'],
  oauth_token_secret: ENV['READABILITY_TOKEN_SECRET']
)

# Fetch archived bookmarks
bookmarks = client.bookmarks

Interactive Card Design

The CSS creates an engaging card-based layout where each bookmark has:

Front face - Title and background image from the article
Back face - Article excerpt and metadata
Flip animation - Smooth 3D transform on hover

The cards use CSS 3D transforms to create a flipping effect that reveals additional information about each article when you hover over them.

Key Features

Responsive design - Cards adapt to different screen sizes
Visual appeal - Each card shows the article’s featured image
Rich metadata - Article excerpts, publication dates, and sources
Smooth animations - CSS transitions for polished interactions

Future Improvements

Potential enhancements I’m considering:

Infinite scrolling - Load more bookmarks as you scroll
Responsive grid - Replace fixed-width layout with flexible grid
Filtering - Sort by date, source, or tags
Search functionality - Find specific articles quickly

Reflection

This project combines API integration, responsive design, and interactive CSS to create something genuinely useful. It’s a great example of how modern web technologies can transform simple data into engaging experiences.

The combination of Ruby for backend processing and CSS for frontend interactions creates a fast, visually appealing way to browse through saved articles.

From RVM to rbenv

Tue, 08 Oct 2013 00:00:00 GMT

I recently switched from RVM (Ruby Version Manager) to rbenv for Ruby version and gem management. This isn’t so much of a ‘howto’, as a dump of my bash history for anyone looking to make a similar transition.

Why I Left RVM

RVM had several issues that frustrated me:

Complicated gem and Ruby version management - The system felt overly complex
Unclear storage locations - I never knew where gems and Ruby versions were actually stored
Confusing gemset commands - The gemset system was hard to understand and manage

Why rbenv is Better

rbenv offers several advantages:

Simpler to understand - The system is more transparent
Works well with Bundler - Better integration with modern Ruby workflows
Easier project-specific Ruby version management - .ruby-version files just work

The Migration Process

Here’s the process I followed to switch:

Completely remove RVM - Clean out all RVM-related files and configurations
Clean out old Ruby and gem installations - Start fresh
Install rbenv via Homebrew - Use the package manager for easy installation
Install desired Ruby versions - Install 1.9.3 and 2.1.4 (the versions I needed)
Set up default gems - Install commonly used gems
Install rbenv plugins - Add rbenv-bundler for better Bundler integration

The Result

The goal was to create “a decent local ruby environment that I actually understand.” rbenv delivers on this promise by being:

Transparent - I can see exactly what’s happening
Simple - No complex gemset management
Reliable - Works consistently across projects

Key Commands

The most important rbenv commands I use daily:

rbenv versions          # List installed Ruby versions
rbenv global 2.1.4      # Set global Ruby version
rbenv local 1.9.3       # Set local Ruby version for current directory
rbenv rehash            # Refresh rbenv shims

The switch from RVM to rbenv was one of the best development environment decisions I’ve made. If you’re frustrated with RVM’s complexity, rbenv is definitely worth considering.

New Job, New Website

Wed, 02 Oct 2013 00:00:00 GMT

I’ve recently transitioned from being a designer to a Ruby developer in London. As part of this change, I decided to build a completely custom website using Sinatra rather than relying on existing platforms.

Why Build Custom?

After trying various blogging platforms, I couldn’t find one that met my specific requirements:

Writing in Markdown - I wanted to write everything in Markdown
Full control over HTML and CSS - Complete creative freedom
Easy image management - Simple way to include images
Understanding all the code - I wanted to know exactly how everything worked

The Technical Setup

The website is built using a custom Sinatra application with several key features:

Static assets compiled locally - CSS and JavaScript are processed before deployment
Custom Redcarpet renderer - Markdown is parsed with custom formatting rules
Special tag system - Images and gists can be inserted using custom tags like {{image: 1}}
Pygments syntax highlighting - Code blocks are highlighted using Pygments.rb

Deployment

The site is deployed to Heroku with New Relic monitoring to prevent the app from going to sleep. This ensures fast loading times even during periods of low traffic.

Custom Styling

I’ve implemented custom styling for all standard Markdown elements:

Lists - Both ordered and unordered with custom styling
Blockquotes - Styled for emphasis and readability
Code blocks - Syntax highlighted with clean typography
Tables - Responsive and well-formatted

Reflection

This project reflects my journey from designer to developer. Rather than using off-the-shelf solutions, I prefer building custom tools that give me complete creative and technical control. The site was quickly developed and deployed, proving that custom solutions don’t always require extensive development time.

The key is understanding your exact requirements and building just what you need, nothing more.

MoD Email Subjects with AppleScript

Fri, 28 Jun 2013 00:00:00 GMT

The work I do with the RAF and Army requires me to send emails with the date and security classification included, like this: “20130628-The Subject-U”.

I must do this at least 30 times a day, and earlier on I was that fed up with copy/pasting dates that I decided to write a script to do it for me. I did try this once before, but Mail.app’s API wasn’t very robust at the time and the action relied upon simulating keypresses which wasn’t exactly reliable.

The following script adds the date and PM to the subject of the foremost Compose Mail Window. It’s a little smarter than my previous attempt too, in that it replaces the date if it’s already there and leaves the PM alone if it exists already.

This one opens a reply to the selected message, with the “Re:” in the right place:

Using Applescript is awkward to say the least - Russell Beattie puts it quite well:

Using AppleScript is like being tied down in a black leather gimp-suit at a dominatrix convention, and losing the safety word… The syntax is like Erlang and ancient Greek got somehow mixed together with Visual Basic, and was translated back into English by mentally-challenged ESL students

I did try to make a plugin for Mail.app to add some buttons to the menubar, but after discovering how difficult it is working with Mail.app’s undocumented API, I gave up and created a Service instead.

Despite AppleScript’s quirks, it’s still the most reliable way to automate Mac applications, especially when you need to interact with specific UI elements like email compose windows.

What is Good Design?

Mon, 21 Jan 2013 00:00:00 GMT

The UK Government Digital Service (GDS) has created something special with gov.uk. Moving away from skeuomorphic design trends, they’ve focused on content-first, accessible design that makes government information truly usable.

As John Gruber noted about skeuomorphic design:

“On retina displays… these techniques are revealed for what they truly are: an assortment of parlor tricks”

The GDS approach demonstrates that good design doesn’t need visual tricks. Instead, it comes from:

Content-focused layout that prioritizes information over decoration
Thoughtful typography including their excellent adaptation of the Transport typeface
Accessibility ensuring government services work for everyone
Flat design that focuses on usability rather than visual effects

Andy Budd’s observation rings true here:

“The best designers and developers rarely have more talent. They simply have more time.”

This echoes Teller’s insight about magic:

“Sometimes magic is just someone spending more time on something than anyone else might reasonably expect.”

The gov.uk website succeeds because the team invested time in getting the fundamentals right: clear typography, logical information architecture, and user-centered design principles.

Good design, it turns out, is less about flashy effects and more about well-designed content, typography, and layout—combined with the time to experiment and refine until everything works seamlessly together.

A Simpler Responsive Grid

Tue, 05 Jun 2012 00:00:00 GMT

After making use of various complicated CSS grid systems, I’ve been using a simple percentage-based grid for the last year or so. It’s based on a 1000 pixel wide container with 63 pixel columns and 20 pixel gutters. The outside gutters at the extreme left/right are 12 pixels to produce a nice round number.

By using a 1000 pixel wide container, the maths is easy when using percentages. each column is 6.3%, gutters are 2% and so on…

By setting a width on the container of 100% and a max-width of 1000 pixels, and thereafter using percentages for all widths, everything resizes nicely:

#container {
    margin: 0 auto;
    max-width: 1000px;
    width: 100%;
  }

  #my-box {
    width: 14.6% /* Two columns wide - (2 * 6.3)+2 */
    margin-left: 1.2% /* Covering the first two columns */
  }

I’ve knocked together a quick example page (code) that shows the columns. One problem with percentage-based widths is that because of the box model, any borders or padding will be added onto outside of the box. Obviously this can be a drama if you’re using pixels to declare your borders and padding.

The easy solution to this is the box-sizing property:

#my-other-box {
    width: 31.2% /* Four columns wide */
    margin-left: 9.5% /* Covering columns 2 to 5 (1.2 + 6.3 + 2) */

    box-sizing: border-box;
    border: 2px solid red; /* will be rendered inside the box */
  }

Although this property isn’t supported in IE7 and below, it’s a useful way to control the box model and make responsive design easier.

Danny Smith - Articles

Introducing Astro Editor

What is it?

Why?

But why?

Where we at now?

So what’s Next?

Like & Subscribe plz

Quite The Journey

Moving this site to Astro

Why Astro?

Modern, Simple & Content-First

Astro Components & MDX

MDX Components

So Where Am I Now?

Content Collections

Plugins

Components

Future Plans

AI and ADHD

Me and ADHD

Embryonic Thoughts on AI & ADHD

1️⃣ A Focussed Context Window (for me, not the LLM)

2️⃣ Meetings Etc

3️⃣ Faster Side Quests

4️⃣ Context Switching When Bored

Wrapping up…

Personal CRMs Aren't What I Need

Building Healthy Remote Organizations - The Silent Enabler of Success

So what does a healthy organisation look like to me?

So when should you start thinking about organisational health?

So how do we start getting healthier? 🌱

Guiding Principles 📜

1️⃣ Have an internal focus

2️⃣ Beware organisational debt

3️⃣ Human + System

4️⃣ Behaviours & habits over processes & tools

5️⃣ Strive for clarity

6️⃣ Practice simplicity

7️⃣ Harness the power of principles

8️⃣ Create frameworks (as well as tools)

Website Redesign Part XVI - A Header and Footer for Articles

The Article Header

The Article Footer

The Code

Auto Generating Jekyll Posts that Redirect to Medium

Website Redesign Part XV - A typographic system for the rest of this site

Deciding on a typeface

Text Styles & Components

Website Redesign Part XIII - Taking Stock of Content

A Content audit for this site

Organising the post-its

By type

By author

By professional or personal

By Importance

By Permanence

But what about the actual content?

How is all this useful?

Keeping it simple

Wrapping up

Footnotes

Website Redesign Part XIV - Stepping Into Figma

Text Styles

Colour Styles

Grids

Components

Summary

Website Redesign Part XII - Responsive Images

SRCSET

The picture element

Images on this website

How do we automate this stuff?

Install the stuff

Is it worth it?

Full-bleed Images

Summing up

Footnotes

Website Redesign Part XI - Code Blocks and Section Rules

The CSS