Guidelines for a website
A website is a complicated thing.
If you don't have a clear idea of what you want to do, there are a lot of different ways to end up with something that, plainly, stinks.
Impressively, it seems that some of the world's premiere institutions of the written word struggle with this just as soon as that word needs to be wrapped in an <html>.
Have you ever clicked a link, hoping to read something insightful from a great writer, just to become locked in battle with the page it's on, which is desperately trying to get you to do anything except read what you came there for?
Sure you have.
That's like 40% of what the web is these days.
Now, admittedly, I can't exactly claim to be a great designer myself.
I've got what you might call “basic” visual aesthetic tastes.
I also don't spend a great deal of time working in the browser, so it's easy for me to forget about some of the various things I care about in a website.
So, this page is primarily for myself, to remember my own design goals, inspirations, and practices.
I'm putting it on this site so that it's definitely available when I want to use it, but maybe it'll be useful to somebody else, too.
Websites that work well
First, hello, future me and anyone else reading.
Let's talk about what actually makes a website good.
This is useful not only because people have different opinions, but also because the web is versatile, and different uses of web technology imply different behaviors.
For example, web art, the kind that Everest Pipkin makes, shouldn't be judged the same way as a blog post or a web app.
Some of the stuff that Steven Wittens does on his site acko.net is similar; while his site is visually great and technically impressive, all the heavily animated whizzing-about going on on the site would be kind of miserable if it were happening on essentially any website that wasn't essentially a tech demo for 3D graphics in the browser.
Complex web apps are yet another thing altogether.
I have very little to say about, say, Google Maps as a “website”, except that it seems good at being a big interactive map.
As far as I'm concerned, websites like that are more or less magic.
That said, though, sophisticated web apps like that—web apps that really need that degree of sophistication—are pretty rare.
There aren't that many websites where “what if we used wasm?” is a reasonable question.
So, for everything else, all those sites that are essentially fancy text-and-image delivery systems, what makes a site good?
Well, some universally good things are compactness and accessibility.
By compactness I mean the amount of data your browser downloads shouldn't be much bigger than it has to.
Plenty of people have written about this before; Maciej Cegłowski did the canonical talk on the “website obesity crisis” (sadly, apparently, half-broken at this time).
Dan Luu has done some great writing on this as well, focusing on the impacts of bloated sites on both slow and intermittent internet and slow devices.
Incidentally, danluu.com itself is a very good, if extreme, example of a compact website.
There is also this motherfucking website, which uses nearly as many bytes on obscenity as it does on markup (I counted).
I also mentioned accessibility.
Accessibility is a very good thing if you want people to use your thing.
Accessibility includes the typical topics of screen-readers and semantic HTML, but it's broader than that.
I would define accessibility on the web as something like “usable, according to many different preferences and needs.”
Because there are many ways people use the web, and many levers of control available to a user.
An accessible site should use responsive design, so that people can read a site easily on whatever screen they want, and at whatever font size or zoom level they want.
Dark mode is another ubiquitous user setting, which a lot of people get very bothered about if they can't manage, and respecting it in this site (as of this writing) costs just 229 bytes of CSS. (Even Dan Luu's site respects dark mode!)
Speaking of fonts: in my opinion, an accessible site should, preferably, allow users to control the font they use to read it.
I'm not a typeface designer or a design firm, and my page isn't about type, so what business is it of mine what fonts are used by people reading my site?
I'm going to deliver half a megabyte of font data just to make sure people aren't able to read text the way they want to?
Some folks want that nice dyslexia-friendly font with the fat bottom.
Some people want a classy, newspaper-like serif.
Some people want Comic Sans.
No joke, my manager uses Comic Sans as his default browser font.
And more power to him!
Moving on to other ways a person would access a website.
Have you ever tried printing a web page?
How did it go?
I think sites do better at this these days than they used to, but it still feels like a treat these days to print out a web page and get something fully functional.
Apparently, image layout is the hardest part.
The High Country News site, for example, does an okay job with print styling, but slices images in half across page breaks.
Low-tech Magazine deserves a special shout-out for formatting their newer articles in a nice looking multi-column format, and especially for taking into account the fact that you can't, you know, click on links on a piece of paper, but it still tends to leave huge ugly blank spaces around large images.
Okay, just a couple more kinds of usability to note.
Not everybody who uses the web is good at English, and nor should they be.
Doing some basic things to help machine translation work well is a Good Thing, and not particularly difficult (so long as you don't have to write the translation engine yourself!)
Lastly, there's usability for people with slow and intermittent networking.
The first clear way to achieve this kind of accessibility is compactness, which I already described, but there's some more beyond that.
There's raw speed, which can be achieved with nice things like minification and compression, though with a sufficiently compact site those don't actually save a whole ton of bits (you'll note this site doesn't use either).
On top of speed, though, there's also networking predictability and control.
When your access to the internet is more complicated than just “yes” or “no”, being able to predict and manage network access has real value.
Alexander Petros describes this well in Who's Afraid of a Hard Page Load?:
Every day I ride the New York City Subway.
For my carrier, most of the stops have cell service, and most of the tunnels between stops do not.
When I read web pages while riding, I am keenly aware that if I click a link while I don’t have service, not only will the page fail to load, I will probably also lose access to the one I’m currently reading.
Everyone who uses a web browser understands this behavior on some level.
So I avoid clicking links until I’m at a stop.
This might seem like something advanced, but it's really the most basic and predictable behavior of the web.
If I'm looking at a page, I should be able to keep looking at it.
If I click a link, it makes sense I wouldn't be able to load it if I don't have internet.
Once that linked page loads, though, I should be able to keep looking at it.
This is Just Works stuff that really sucks when it stops, and having it is worth a lot.
So, okay.
Those are some qualities that make a site good and usable.
It should be predictable, printable, translatable, accessible, responsive, configurable, and compact.
But what about other kinds of “good”?
What kind of sites are actually doing something interesting or inspirational?
What sites are cool?
Websites that are cool
Okay, first of all, let me admit what's already extremely predictable: I have a different idea of what's cool than most other people do.
I like tools that are small and high-leverage, objects that expose their component parts, and systems that are complex and malleable.
I like sites that use or expose HTML in interesting ways. This self-described HTML quine is essentially as far as you can go in this direction, but other projects like the html review are also troves of creativity.
I'm also fond of sites that interact with the real world in ways that most sites usually don't — sites which respond to their own energy use and display their own server's physical reality.
The Low-tech Magazine seems to be cited by most as the original on this, but the Solar Protocol project adds some cleverness to that, grouping several geographically-distributed solar servers together to direct traffic around the planet as solar availability changes.
Other such projects exist, too. compost.party is a tiny shared server modeled heavily on the Low-tech Magazine solar server, including the image dithering.
There are a lot of good ideas on the Damaged Earth Catalog, and organizations like LIMITS.
Lots of these pages don't do very much of what I describe as “working well”.
Like I mentioned, many of them are effectively interactive art, and it doesn't make much more sense to print interactive art than it does to print a sculpture.
Sadly, I also can't very easily follow the lead of a lot of these sites right now, since my own internet situation at home is difficult.
I don't have a public IP address to speak of, and doing a small-site-hosted-on-the-farm doesn't seem particularly useful if you can't see it without going through some kind of Cloudflare tunnel to do so.
So, there's some disconnect between the sites I think are good (work well) and those I think are good (are cool).
When the opportunity comes, though, I plan on integrating the two ideals in this site.
As a side note: the LIMITS page looks pretty dang good when printed.
Making a good website
Okay, so we have an idea of what we want a website to be like.
How do we actually make that?
Well, in terms of the actual site serving, that's coming from a shell script (specifically a script written in es.
That has some benefits, but it's a story for a different page.
The site is currently dead simple, but for pages that are a bit more dynamic, something like htmx seems fairly ideal.
As far as the stuff that runs in the browser goes:
The overall HTML structure is inspired by these tips from Aaron Parks.
Doing markup in this way is nice for the server, too, since it can just smash files together pretty blindly without being markup-aware.
This page from Patrick Weaver is a nice high-level view on more or less all the HTML elements.
For screen readers and mouse-based navigation, using the fancy semantic elements is a Good Thing.
Also, try to make the text context of links contain meaningful text content, instead of “click here” or whatever.
The MDN is a great source for documentation on responsive design, and as far as strategies go, mobile-first is the right one.
Print CSS (for which the “Printing” MDN documentation is valuable) is mostly a matter of setting display: none; on the appropriate elements, but for dealing with link unclickability, this is a good trick:
@media print {
a[href]::after {
content: " (" attr(href) ")"
}
}
CSS for displaying link targets in printed pages
Good translation support is mostly a matter of declaring what language content is in.
That's done via the lang attribute on tags.
Since this site is generally in English, <html lang=en-US> is set on every page.
But, since this site has some content that isn't in English, declaring the right languages for the right text is good.
Note this also improves text rendering: hyphenation is based on language, so declaring the language being used helps avoid weirdness.
Declaring the encoding with <meta charset=UTF-8 /> is good too.
UTF-8 is the only encoding to use on the web these days.
One last note about languages!
We generally don't want code translated at all, even if we're translating text from English to something else.
For general text, that can be hinted at with a translate=no attribute on an element, but for code, that isn't necessary, as long as everything is wrapped in one of the following elements: kbd, for input to a computer; samp, for output from a computer; or code, for other code.
Note that pre doesn't prevent translation by itself.
Okay, that's all for now.
This is a living page so expect it to change over time as I slowly get less wrong.