A draft design document for this site

Good design is innovative, useful, aesthetic, understandable, unobtrusive, honest, long-lasting, thorough, and friendly to its environment.\

Good design is as little design as possible.

Dieter Rams’ Ten principles for good design, summarised by me

This site aspires to be an exploratory medium for its author and its reader, respecting both.

To that end, I will try to formalise some of the principles and considerations that underpin the design of this site, with the goals of: allowing me to track how my approach to this project changes through time, giving users of this site a better understanding of its purpose.

More such design principles still exist purely in my head, including numerous to which this site does not yet adhere – over time I mean to reconcile those inconsistencies and present an ever fuller picture of this sites design posture. Though I feel quite strongly about a number of these principles and their off-shoots, as well as the anti-patterns they seek to address, I welcome comment, criticism, and questions about these decisions.

For a glimpse at the future of this site, see the Site Enhancement Proposals or if you’re technically minded and fancy a deeper peek behind the curtain, take a look at Building this site.


Principles I’m still forming

Minimalist, where appropriate

Featureful but uncluttered. Design should enhance the content but otherwise disappear, being almost maximally unobtrusive while presenting powerful tools for navigation and discovery.

Principle of least astonishment

Satisfying the principle of least astonishment means doing what the user expects. Surprise is one of our most powerful emotions, it is at the heart of learning, after all if we were not surprised by something then we expected it, and if we expected it then on some level we already knew it.

The process of writing is often one of surprise, of learning, frequently I discover a strength of feeling, a depth of knowledge, or (more often) a shallowness of knowledge that I did not expect through that process. I hope too that from time to time I will succeed in surprising you, the reader, but I do not mean for that surprise to spring from the design and structure of this site, let that arise from the content instead. Its design should be predictable, intuitive, even boring, allowing the user to forget about it almost entirely, meeting them where they are and taking them only where they mean to go.

Jekyll does what you tell it to do — no more, no less. It doesn’t try to outsmart users by making bold assumptions, nor does it burden them with needless complexity and configuration. Put simply, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content.
Jekyll’s Design Philosophy


If the principles above lay out my intent for the design of this site, the particulars below are the implementation details arising from those ideals.


  • Line width
  • Fonts


URLs can’t – and shouldn’t – be everything all at once1. A URLs purpose is made plain in its name – Uniform Resource Locator We can carefully expand upon that simple destiny by thinking about what a schema for Useful Resource Locators might look like.


Providing feeds for users to subscribe to improves accessibility and represents a small, easy contribution to the health of an open web. All content on the site should be made available through programmatically produced feeds.

Feeds should be collocated, all residing at silasjelley.com/feeds/$FEED

Take silasjelley.com/feeds/notes, why not place its feed at silasjelley.com/notes/feed? In that example I agree that the latter structure is just as elegant and useful as the former. But what if I want to create arbitrary feeds such as a feed that combines the notes and glossary collections? Where would I put that?

Full and partial feeds should be made available.


A Changelog should document meaningful changes or additions to the shape of this site, things like new features, significant stylistic changes, bug fixes etc.

Design proposals

Here are some of those things, principles to which this site does not yet fully adhere, alluded to at the beginning.

Undocumented features

My bad design

My design missteps are already too many to count or remember. Some of them are captured in the highly abridged record of changes in this sites’ Changelog but some are not, I am an incompetent and flawed design myself. Nevertheless, here are a few

A handwritten font : At some point I decided it would be pleasing to add a handwritten fontface for time elements and footnotes. It wasn’t particularly pleasing, and moreover it was disrespectful of users. Though it was limited to minor parts of the site, it made those parts harder to read and incurred another network request to fetch the font for new visitors.


The power of good design — Dieter Rams
Software Design Description – Wikipedia
How to Write a Design Document – Professor John D. Kubiatowicz
Keep a Changelog
Semantic Linefeeds – Brandon Rhodes
On Short URLs – qntm.org
Returns to Design – Gwern Branwen
Design at jwz – Jamie Zawinski
URL Design - Kyle Aster\

  1. Sure, technically speaking most browsers will support URLs of almost any length – though issues may arise above 2048 characters – so there’s little stopping you jamming entire (short) documents into a URL, but… please don’t.↩︎︎