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
- Respectful, of users and a wider habitat
- Useful, to you and to me - Accessible, progressively enhanced - Simple - Durable, through time - Principle of least astonishment - Able to improve my thinking process
- Iterative
- Honest
Principles I’m still forming
- If a system is to serve the creative spirit, it must be entirely comprehensible to a single individual.
- A system should be built with a minimum set of unchangeable parts; those parts should be as general as possible; and all parts of the system should be held in a uniform framework.
- Languages exist to provide a framework for communication.
- Systems that are of sound design will persist, to be supplanted only by better ones.
- System designed around the average person are doomed to fail.
- DRY - Don’t repeat yourself. This is a principle of programming and needs therefore to be approached with caution in it’s application to prose, but I do still think it can be of use. I don’t aim to avoid returning repeatedly to the same ideas, in fact that is exactly what I aim to encourage. What I want to avoid is the wholesale copying of blocks of texts. Be that from my journal to my notes dir, or within linked documents. Reference is better than repetition as it were. The chief transgression of this principle in the system as a whole at the moment is the duplication of certain passages that are lifted from my journal. I want instead to be able to publish directly from my journal in a ‘scoped’ way. This has been why I return again and again in my thinking to the idea of an ‘outliner’ (as proselytized by Dave Winer) as a tool of perhaps unique qualification here. \
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
Particulars
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.
Typography
- Line width
- Fonts
URLs
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.
Feeds
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.
Changelog
A Changelog should document meaningful changes or additions to the shape of this site, things like new features, significant stylistic changes, bug fixes etc.
Backlinks
I intend for this site to make heavy use of backlinks, references between its documents. This will become more important – and more useful – as the depth and number of documents grows, allowing users to explore (ideally) the whole site from any starting point.
Design proposals
Here are some of those things, principles to which this site does not yet fully adhere, alluded to at the beginning.
- Stricter adherence to the dogma that Cool URIs don’t change (see also) backed by an approximately immutable record of every URI/URL ever minted on this site along with an automated means of ensuring all such URIs still resolve in perpetuity.
- Expand support for [admonitions].
-
Image dimensions should be looked up during builds & inserted into
<img>tags as browser hints. - Durable and accessible preservation of all external resources linked to from any document on this site.
-
Block level addressing. Block level addressing would permit transclusion.
- Proposed syntax:
{+H7C9X}- Draft specification: Find all instances of{+, look forward for matching closing brace}. If unfound by end of line/within ten chars, exit and emit error (ERROR: Block ID closing brace not found). IDs should be removed or hidden in output HTML. IDs should not be parsed when inside code blocks. Transclusion will necessarily be limited/half baked if working in only markdown, as in the transcluded block will not be visible in the referencing document, only it’s ID - this somewhat defeats the value-add. This again is an argument in support of switching to a database as the primary data store, that way transclusions could be visible immediately and update instantly/automatically in referencing docs. - Integrate something like littlefoot.js
Undocumented features
- Use of non-standard markdown features. Any features of the markdown pipeline should be documented to ensure that those same extensions can be ported over if ever I change markdown processors. - Admonitions
- Cascading Style Sheet
- Intent for all pages to be valid XHTML
- Accessibility
- Optional (and progressive) modal for image viewing. Optional in that I don’t want it loaded on every page, only on those that might warrant a closer looking at the included images. Particularly suited to image heavy posts, such as my journeys.
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.
References
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\
-
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.↩︎︎
