Ben Ward

The Pastry Box: Technical Style


San Francisco

Recently, the internet delighted in petty squabbles between developers over what I’ll generically refer to as ‘technical style.’ I’m going to skip the sideshow of specifics, but they each involved punctuation, to a greater or lesser degree. Wound up inside these arguments over technical style are preferences over tooling, education, expected competence, different interpretations and experiences of interoperability.

It’s not a generational divide based on age (although there’s possibly some correlation), and it’s not defined by total accrued experience (although there’s possibly some correlation.) It’s just trends. Where a technology permits flexibility, people will rightly explore and experiment, looking for variations that are somehow better than the status quo. We iterate on performance, clarity, and aesthetics all the time in the products we build, and so we do with the tools we use to build them too. It comes in waves, and sometimes cultivates a scene along the way. People have been doing this with HTML, CSS, and JavaScript for a very long time. This industry as we know it grew up on the back of trends, perhaps most influentially the post–2000 adherence to XHTML: Although at its core XML is a bad idea for web publishing (unrecoverable rendering errors for content, brilliant!), the trend carried with it a revolutionary education in separated concerns, cross-browser design, and graceful degradation that lynchpins web professionalism today. Each successive wave of web developers can be expected to experiment in their own way, because this technology stack allows us to, and because it’s a powerful way of learn in and of itself.

As people learn, they document findings, either adding to the common school of thought, or rebelling against it. There will be both right and weak conclusions. With time and experience, the better writing turns into more substantial references, like books. Then those articles and books depreciate as the examples within them age.

Here’s our problem: In each generation of web development, we are leaving people to relearn the same lessons of the last. There are techniques backing various aspects of technical style that should be stable and constant by this point. There were strong reasons for one style to be advocated over others in the first place, right?

Two two noisy tribes: One experimenting with their web technology, fluency and productivity through variations in style. Opposition to this starts with a legitimate technical hurdle, but is followed by a torrent of establishment and dogma. Given that research over ten years has gone into establishing the style guide of the web, surely someone would be able to simply reference an earlier work? Everyone interested could revise the issue, reestablish the conclusions, and move on.

But nobody referenced anything in these debates.

Instead we got superiority complexes, and snark, and trolling, and image macros. In vacuum of authoritative references, some rushed out to write new ones, immediately muddling technical worth with ego, and vapid condescension. Elsewhere, a banal portmanteau is uttered with hair-brained sincerity. A kitten dies.

We’ve taken our knowledge for granted, passed it on with examples and well-meaning advice, but failed to establish our references. It’s a different kind of archival shortcoming. We often think of redundantly storing all of our web content, but here we’ve failed as librarians. We knew the knowledge was out there, we trusted the knowledge, but when it was challenged no-one had a robust answer. In its place, dogmatic presumption undermines a lot of the effort around education and best practice, and the cooperative attitudes of our community.

Besides insufficient cataloguing, one reason for uncontentious, enduring references on technical style to evade us is because they’re attached to otherwise ephemeral writing. These patterns we take for granted aren’t being documented well enough. Because the examples we use age. Because the contexts they’re presented in become obsolete and confusing as browsers. Because we don’t have time to be librarians, because we’re building new stuff, because we’re teaching by example. This is all defensible, but it’s evidently not good enough. We can’t work from the prescribed style to a full understanding of the language. If we believe in the web, we have an obligation to support the education of our peers and ourselves; the technology we use is always changing, no-one will ever stop learning. Perhaps this requires a kind of reference writing that blogs and magazines have neglected, but which is done well in other technical writing efforts that avoid issues of style: API documentation, for example.

Technical style is just one small piece of building a successful technical platform from the web. If we care about style—and apparently we do—we need to do better at recording it. We need to build better teaching materials, we need to ensure that people can establish a full understanding of the web and its technology, not just the pieces we ring-fenced as ‘safe’. We need to write for our industry’s encyclopedia, not just its tabloid.

You can file issues or provide corrections: View Source on Github. Contributor credits.