In this week’s roundup, a handy bookmarklet for inspecting typography, using await to tinker with how JavaScript modules import one another, plus Facebook’s in-app browser is only posing as one. Let’s get into the news!
Check if your content breaks after increasing text spacing
Dylan Barrell from Deque has created a bookmarklet that you can use to check if there are any issues with the content or functionality of your website after increasing the line, paragraph, letter, and word spacing, according to the “Text Spacing” success criterion of the Web Content Accessibility Guidelines.
The proposed top-level await feature is especially useful in JavaScript modules: If module A uses top-level await (e.g., to connect to a database), and module B imports module A — via the import declaration — then the body of B will be evaluated after the body of A (i.e., B will correctly wait for A).
Top-level await enables modules to act as big async functions: With top-level await, ECMAScript Modules (ESM) can await resources, causing other modules who import them to wait before they start evaluating their body.
AMP has created a new multi-stage loading indicator that has better perceived performance (tested on 2,500 users): It shows nothing until 0.5s, then an intermediate animation until 3.5s, and finally a looping spinner after that.
AMP has released the <amp-script> element which, for the first time, allows AMP pages to add custom JavaScript, with some constraints: The code runs in a separate worker thread and requires a user gesture to change page content (via AMP Project).
The HTML Standard has made autofocus a global attribute that “applies to all elements, not just to form controls” (e.g., this change enables <div contenteditable autofocus>, but no browser supports this yet) (via Kent Tamura).
Facebook’s in-app browser (powered by Android’s WebView) is not a browser: “Facebook is breaking the web for 20–30% of your traffic because you aren’t demanding they do better” (via Alex Russell).
Read more news in my new, weekly Sunday issue. Visit webplatform.news for more information.
You’ve created a Progressive Web App (PWA), designed an icon to represent it, and now you’re installing it to your Android home screen.
But, if you have a recent Android phone, your icons will show up like this:
What happened? Well, Android Oreo introduced adaptive icons, a new icon format that enforces the same shape for all icons on the home screen. Icons that don’t follow the new format are given a white background.
However, there is a new web feature called maskable icons that is coming soon to Firefox Preview and other web browsers. This new icon format will let your PWAs have their own adaptive icons on Android.
I work at Mozilla and have implemented support for maskable icons in Firefox Preview. I’ll show you how to add them to your own PWAs for Android.
What are maskable and adaptive icons?
Until a few years ago, Android app icons were freeform and could be any shape. This meant that web apps could also reuse the same transparent icon when pinned to the home screen.
However, manufacturers, like Samsung, wanted to make all icons on a device the same shape to keep things consistent. Some manufacturers even wanted different shapes. To deal with the variety of requirements from manufacturers and devices, Android introduced “adaptive icons.” You supply an image with extra space around the edges, and Android will crop it to the correct shape.
But web apps are designed to work on any platform, so they don’t have APIs to create these special Android icons. Instead, icons would get squished into white boxes like this:
Lo and behold, last September a brand new API descended upon us and was added to the W3C spec. Maskable icons allow web developers to specify a full-bleed icon that will be cropped. It’s platform agnostic, so Windows could use them for tiles or iOS could use them for icons.
How to create maskable icons
Since the maskable icon format is designed work with any platform, the size and ratios are different from the size and ratios of Android’s adaptive icons. This means you can’t reuse the same asset.
Maskable icons can be any size, and you can continue to use the same sizes that you’d use for normal transparent icons. But when designing the icon, ensure that important information is within a “safe zone” circle with a radius equal to 40% of the image’s size.
The safe zone
All pixels within this zone are guaranteed to be visible. Pixels outside the zone may be cropped off depending on the icon shape and the platform.
Warning: If you already have an Android app, avoid copying and pasting the icon from your Android app to your web app. The ratios are different, so your icons would look too small.
Adding the icon to your Web App Manifest
Once the icons are created, you can add an entry to your Web App Manifest similar to other icon assets. The Web App Manifest provides information about your web app in a JSON file, and includes an "icons" array.
Maskable icons use a special new key, "purpose", to indicate that they are meant to be used with icon masks. Icons with transparent backgrounds have a default "purpose" of "any", and icons can be used for multiple purposes by separating each option with a space.
"purpose": "maskable any"
Preview your icons
Do you want to see what your own maskable icons will look like? I’ve created a tool, Maskable.app, to help you evaluate how the icon appears in different shapes.
The app lets you preview your icon in various shapes that can be found on Android devices. I hope this tool helps you create unique icons for your Progressive Web Apps.
Once you’re satisfied with the results, you can start testing your app with Mozilla’s Reference Browser. This special browser is a testing ground for features before they reach Firefox Preview, and you can use it to check out how your PWA looks. Chrome is working on maskable icon support too.
Tools like PWACompat also have support for maskable icons. You can automatically generate icons for iOS and other devices based on your new maskable icons!
Time to build your own icons
If you want to more control over how your PWA icons are displayed on Android, maskable icons is the way to go. With maskable icons you can customize how your icon is displayed from edge-to-edge. Hopefully this article can get you started on creating your first maskable icon.
Before we come to how to style underlines, we should answer the question: should we underline?
In graphic design, underlines are generally seen as unsophisticated. There are nicer ways to draw emphasis, to establish hierarchy, and to demarcate titles.
If you feel the urge to underline, use bold or italic instead. In special situations, like headings, you can also consider using all caps, small caps, or changing the point size. Not convinced? I invite you to find a book, newspaper, or magazine that underlines text. That look is mostly associated with supermarket tabloids.
But the web is different. Hyperlinks are the defining feature of the internet; and from the internet’s inception, they have been underlined. It’s a universally understood convention. The meaning is crystal clear — an underline means a link.
However, plenty of popular websites have ditched underlines: The New York Times, New YorkMagazine, The Washington Post, Bloomberg, Amazon, Apple, GitHub, Twitter, Wikipedia. When they removed underlines from their search results page in 2014, Google lead designer Jon Wiley argued that it created a cleaner look. Notably though, the majority of these sites have kept slight variances on the traditional lurid blue color (#0000EE) that’s been the browser default since the beginning of the web. While this provides a visual cue for the majority of users, it may not be enough to pass WCAG accessibility compliance.
Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
— WCAG 2.1
WCAG do not strictly mandate using underlines for links, but it does recommend them. Color blind users need to be able to discern a link. You could differentiate them in other ways, such as with a bold font-weight. Or you could keep this long-established visual affordance. But if we’re going to use underlines, we want them to look nice. Marcin Wichary, a designer at Medium, described the perfect underline as:
[…] visible, but unobtrusive — allowing people to realize what’s clickable, but without drawing too much attention to itself. It should be positioned at just the right distance from the text, sitting comfortably behind it for when descenders want to occupy the same space.
Achieving this has traditionally required CSS tricks.
The hacks we’ve had
This is one trick all developers will be familiar with: border-bottom. By emulating an underline using border-bottom, we gain control over color and thickness. These pseudo-underlines have one problem: an overly large distance from the text. They are underneath the descenders of the letters. You could potentially solve this issue by using line-height, but that comes with its own issues. A similar technique utilises box-shadow. Marcin Wichary pioneered the most sophisticated technique, using background-image to simulate an underline. They were useful hacks but are thankfully no longer needed.
Styling real underlines
Finally we can demarcate links without sacrificing style thanks to two new CSS properties.
text-underline-offset controls the position of the underline.
text-decoration-thickness controls the thickness of underlines, as well as overlines, and line-throughs.
You can also specify from-font to both of these properties which will pull the relevant metric from the used font file itself.
UX agency Clearleft make bold use of (pseudo) underlines, calling clear attention to links with colorful styling. Here’s one example of a faux underline:
a {
text-decoration: none;
border-bottom: #EA215A 0.125em solid;
}
Notice that this fake underline is clearly below the descender of the letter „y”:
Here’s the same paragraph, using DevTools to apply the same styling to a real underline using the new CSS properties:
a {
text-decoration-color: #EA215A;
text-decoration-thickness: .125em;
text-underline-offset: 1.5px;
}
You’ll notice I’m using the em unit in my example code. The spec strongly encourages using it rather than pixels so that the thickness scales with the font.
These properties have already shipped in Safari and are coming in Firefox 70.
With the move to Chromium for Microsoft’s Edge browser, we will finally have cross browser support for the text-decoration-style property, which offers the options: solid (the default), double, dotted, dashed, and wavy. When combined, these new properties open up a whole range of possibilities.
Perhaps the biggest upgrade for underlines on the web, however, has come without developers needing to do anything. In the bad old days, descenders were unceremoniously sliced through by underlines, which was far from elegant. Developers used to hack around this shortcoming by applying a text-shadow that matched the background color. text-decoration-skip-ink brought a better way to make space for descenders.
The default value of auto (left) and a value of none (right)
Handily, it’s set as the new default value for underlines; meaning the look of underlines has improved while most web developers remain unaware that this property exists. Should you want an underline to cross over glyphs, you can set this property to none.
Before we come to how to style underlines, we should answer the question: should we underline?
In graphic design, underlines are generally seen as unsophisticated. There are nicer ways to draw emphasis, to establish hierarchy, and to demarcate titles.
If you feel the urge to underline, use bold or italic instead. In special situations, like headings, you can also consider using all caps, small caps, or changing the point size. Not convinced? I invite you to find a book, newspaper, or magazine that underlines text. That look is mostly associated with supermarket tabloids.
But the web is different. Hyperlinks are the defining feature of the internet; and from the internet’s inception, they have been underlined. It’s a universally understood convention. The meaning is crystal clear — an underline means a link.
However, plenty of popular websites have ditched underlines: The New York Times, New YorkMagazine, The Washington Post, Bloomberg, Amazon, Apple, GitHub, Twitter, Wikipedia. When they removed underlines from their search results page in 2014, Google lead designer Jon Wiley argued that it created a cleaner look. Notably though, the majority of these sites have kept slight variances on the traditional lurid blue color (#0000EE) that’s been the browser default since the beginning of the web. While this provides a visual cue for the majority of users, it may not be enough to pass WCAG accessibility compliance.
Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
— WCAG 2.1
WCAG do not strictly mandate using underlines for links, but it does recommend them. Color blind users need to be able to discern a link. You could differentiate them in other ways, such as with a bold font-weight. Or you could keep this long-established visual affordance. But if we’re going to use underlines, we want them to look nice. Marcin Wichary, a designer at Medium, described the perfect underline as:
[…] visible, but unobtrusive — allowing people to realize what’s clickable, but without drawing too much attention to itself. It should be positioned at just the right distance from the text, sitting comfortably behind it for when descenders want to occupy the same space.
Achieving this has traditionally required CSS tricks.
The hacks we’ve had
This is one trick all developers will be familiar with: border-bottom. By emulating an underline using border-bottom, we gain control over color and thickness. These pseudo-underlines have one problem: an overly large distance from the text. They are underneath the descenders of the letters. You could potentially solve this issue by using line-height, but that comes with its own issues. A similar technique utilises box-shadow. Marcin Wichary pioneered the most sophisticated technique, using background-image to simulate an underline. They were useful hacks but are thankfully no longer needed.
Styling real underlines
Finally we can demarcate links without sacrificing style thanks to two new CSS properties.
text-underline-offset controls the position of the underline.
text-decoration-thickness controls the thickness of underlines, as well as overlines, and line-throughs.
You can also specify from-font to both of these properties which will pull the relevant metric from the used font file itself.
UX agency Clearleft make bold use of (pseudo) underlines, calling clear attention to links with colorful styling. Here’s one example of a faux underline:
a {
text-decoration: none;
border-bottom: #EA215A 0.125em solid;
}
Notice that this fake underline is clearly below the descender of the letter „y”:
Here’s the same paragraph, using DevTools to apply the same styling to a real underline using the new CSS properties:
a {
text-decoration-color: #EA215A;
text-decoration-thickness: .125em;
text-underline-offset: 1.5px;
}
You’ll notice I’m using the em unit in my example code. The spec strongly encourages using it rather than pixels so that the thickness scales with the font.
These properties have already shipped in Safari and are coming in Firefox 70.
With the move to Chromium for Microsoft’s Edge browser, we will finally have cross browser support for the text-decoration-style property, which offers the options: solid (the default), double, dotted, dashed, and wavy. When combined, these new properties open up a whole range of possibilities.
Perhaps the biggest upgrade for underlines on the web, however, has come without developers needing to do anything. In the bad old days, descenders were unceremoniously sliced through by underlines, which was far from elegant. Developers used to hack around this shortcoming by applying a text-shadow that matched the background color. text-decoration-skip-ink brought a better way to make space for descenders.
The default value of auto (left) and a value of none (right)
Handily, it’s set as the new default value for underlines; meaning the look of underlines has improved while most web developers remain unaware that this property exists. Should you want an underline to cross over glyphs, you can set this property to none.
The DOM is just a little weird about some things, and the way you deal with attributes is no exception. There are a number of ways to deal with the attributes on elements. By attributes, I mean things like the id in <div id="cool"></div>. Sometimes you need to set them. Sometimes you need to get them. Sometimes you get fancy helpers. Sometimes you don’t.
For this article, I’ll assume el is a DOM element in your JavaScript. Let’s say you’ve done something like const el = document.querySelector("#cool"); and matched <div id="cool"> or whatever.
Some attributes are also attributes of the DOM object itself, so iff you need to set an id or title, you can do:
el.id; // "cool"
el.title = "my title";
el.title; // "my title";
Others that work like that are lang, align, and all the big events, like onclick.
Then there are attributes that work similarly to that but are nested deeper. The style attribute is like that. If you log el.style you’ll see a ton of CSS style declarations. You can get and set them easily:
You can get computed colors this way too. If you do module.style.color hoping to get the color of an element out of the gate, you probably won’t get it. For that, you’d have to do:
let style = window.getComputedStyle(el);
style.color; // whatever in CSS won out
But not all attributes are like first-class attributes like that.
el['aria-hidden'] = true; // nope
That „works” in that it sets that as a property, but it doesn’t set it in the DOM the proper way. Instead, you’ll have to use the generic setter and getter functions that work for all attributes, like:
el.classList.value; // "module big"
el.classList.length; // 2
el.classList.add("cool"); // adds the class "cool", so "module big cool"
el.classList.remove("big"); // removes "big", so "module cool"
el.classList.toggle("big"); // adds "big" back, because it was missing (goes back and forth)
el.classList.contains("module"); // true
There’s even more, and classList itself behaves like an array so you can forEach it and such. That’s a pretty strong reason to use classes, as the DOM API around them is so handy.
Another attribute type that has a somewhat fancy help is data-*. Say you’ve got:
Listen, I am no GraphQL expert but I do enjoy working with it. The way it exposes data to me as a front-end developer is pretty cool. It’s like a menu of available data and I can ask for whatever I want. That’s a massive improvement over REST and highly empowering for me as a front-end developer who desires to craft components with whatever data I think is best for a UI without having to make slew of calls for data or ask a back-end developer to help make me a new bespoke API for my new needs.
But… who builds that menu of data? Somebody does.
If that somebody is a person or team at your own company because you’ve built out your own GraphQL API for your own needs, that’s great. Now you’ve got control over what goes in there (and when and how).
But sometimes GraphQL APIs are just handed to you. Perhaps that is how your CMS delivers its data. Still cool and useful, but that control is at the mercy of the CMS. You still have a menu of options, but the menu just is what it is. No substitutes, to continue the metaphor. If the menu doesn’t have what you need, you can’t go back into the kitchen and add extra sauerkraut to that reuben or have the steak fries come with fried mushrooms.
This came up in a discussion with Simen Skogsrud and Knut Melvær on an episode of ShopTalk. Their product, Sanity, is like cloud storage for JSON data, and a CMS if you need it. A modern product like this, you’d think a GraphQL API would be a no-brainer, and indeed, they have a beta for it.
But instead of GraphQL being the main first-class citizen way of querying for and mutating data, they have their own special language: GROQ. At first glance, I’m like: eeeeeesh, there’s a way to shoot yourself in the foot. Invent some special language that people have to learn that’s unique to your product instead of the emerging industry standard.
But Simen and Knut made a good point about some of the limitations of GraphQL in the context of a third-party handing you an API: you get what you get. Say a GraphQL API offers a way to retrieve authors. A generic API for that is probably designed something like this:
But what I actually want is just how many authors we have on the site. Perhaps I wish I could do this:
{
allAuthors {
count
}
}
But that’s not in the API I was given. Well, too bad. I guess I’ll have to request all the authors and count them myself. I might not control the API.
This means that something like a CMS that offers a GraphQL endpoint needs to make a choice. They are either very strict and you just get-what-you-get. Or, they offer not only a GraphQL API but a way to control and augment what goes into that API.
In Santiy’s case, rather than offer the later, they offer GROQ, which is a query language that is powerful enough you can get whatever you want out of the (JSON) data. And rather than making it this proprietary Sanity-only thing, they’ve open sourced it.
With GROQ, I don’t need any permission or alterations to the API to ask how many authors there are. I’d do something like…
{ "totalAuthors": count(*[* in authors]) }
(I actually have no idea if the above code is accurate, and of course, it depends on the JSON it is querying, but it’s just conceptual anyway.)
By giving someone a query language that is capable of selecting any possible data in the data store, it has a big benefit:
You can query for literally anything
You don’t need a middle layer of configuration
But it comes at a cost:
Complexity of syntax
No middle layer means less opportunity for connecting multiple APIs, exposing only certain data based on permissions, etc.
In advance of a recent podcast with the incredible technical writer and Smashing Magazine editor-in-chief Rachel Andrew, I gathered up a bunch of thoughts and references on the subject of technical writing. So many smart people have said a lot of smart things over the years that I thought I’d round up some of my favorite advice and sprinkle in my own experiences, as someone who has also done his fair share of technical writing and editing.
There is a much larger world of technical writing out there. My experience and interest is largely about web technology and blogging, so I’m coming at it from that angle and many of the people I quote throughout are in that same boat.
Picking something to write about
If you want to write for CSS-Tricks and you ask me what you should write about, I’m probably going to turn that question around on you. It’s likely I don’t know you well enough to pick the perfect topic for you. More importantly, what I really want you to write about is something that is personal and important to you. Articles rooted in recent excitement about a particular idea or technology always come out better than dictated assignments.
My best advice:
Write the article you wish you found when you googled something.
That said, I do maintain a list of ideas specifically for this site. Any writing can be done on assignment and sometimes that elicits the spark needed for something great and on-target for the audience of a site.
Write at the moment of learning
The moment you learn something is the best time to write. It’s fresh in your mind and you can remember what it was like before you understood it. You also understand what it takes to go from not knowing to knowing it. That’s the journey you need to take people on.
If you don’t have time, at least try to capture the vibe wherever you save your ideas. Don’t just write down „dataset.” Write down some quick notes like, „I didn’t realize DOM elements had a .dataset property for getting and setting data attributes. I wonder if it’s better to use that than getAttribute.” That way, you’ll be able to reload that realization in your brain when you revisit the idea.
Here’s some advice Rachel shared that I don’t see taken advantage of nearly enough:
There is a sweet spot for writing technical posts and tutorials. Write for the professional who hasn't had time to learn that thing yet, and link it back to things they already know. For example explaining a modern JS technique to someone who knows jQuery.
Tell me about how this new framework relates to Backbone. Tell me how this CMS relates to WordPress. Tell me how some technology connects to another technology that is safe to assume is more widely understood.
Technology changes a lot, but what technology does doesn’t change all that much.
Careful with that intro
The main comment I add on tutorials I review is to ask for an intro that describes what the tutorial is about. I'm 600 words in and still don't know what the tutorial is about and who it is for. #writing
Not getting to the point right at the top of technical articles is a dang epidemic. The start of a technical article is not the time to wax poetic or drop some cliché light philosophy like, „Web design sure has changed a lot.” You don’t have to be boring, but you do need to tell me what this article is going to get into and who it is for.
“Does the title make the article sound interesting?” If the title interests a reader, they’ll typically read the intro and decide, “Is it worth my time reading the whole thing?” A common mistake I see in a lot of technical posts is either too much introduction or, alternatively, far too little.
A single well-written paragraph can set the stage for a technical blog post.
Careful with the title, too
I remember a conversation from years ago with content strategist Erin Kissane where she strongly advised me to choose boring titles for everything. Not just the title of blog posts, but for everything, including the names of sections, tags, and even subheadings within posts.
Here’s the thing with boring: it works. Boring isn’t the right word either; it’s clarity. The world is full of clickbait, and maybe that’s effective in some genres, but technical blogging isn’t one of them.
A terrible version of the same: Build a web app with modern technologies in 30 minutes!
What’s a web app? What technologies? What’s modern about them? What’s with the weird time limit?
SEO matters and Margaret’s article is going to do a lot better in both the short and long term with that clear title.
The outro
Ben Halpern says that the next most important thing after the intro is:
[…] the last paragraph.
People don’t read top-to-bottom the moment when they arrive, so there is a good chance it’s the second paragraph people read. Personally, I find the beginning a lot more important than the ending, but there is a certain art to the ending as well.
A lot of people just <h2>Conclusion</h2> and write a few words about what was just went over. Honestly, I don’t hate that. It falls into this time tested pattern:
Tell ’em what you’re gonna tell ’em
Tell ’em
Tell ’em what you told ’em
That helps your message sink in and brings things full circle. Technical blogging isn’t terribly different from marketing in that sense. You’re trying to get people to understand something and you’re using whatever tricks you need to to get the job done. A little repetition is a classic trick.
[…] the wall of text can be easily be made less intimidating and appear much more visually appealing through the use of visual elements that break it up. The easiest is to simply place section subheadings throughout your post.
I agree: subheadings are probably the easiest and most powerful trick for scannability.
Other methods:
Lists: Like what I’m doing right now! I didn’t have to use a list. Paragraphs might have worked as well, but a list makes contextual sense here and is probably tricking some of you into reading this. Or at least scanning it and getting some key points in the process.
Images: Please make them relevant and contextual. Skip the funny GIF. Screenshots are often great in a technical context because they provide a visual to what might otherwise be a difficult concept to explain. I like Unsplash for thematic imagery, too, but you can do better than a random picture of trees, a woman drinking coffee, or a random rack of servers.
Illustrations: The abstract nature of an illustration is your friend. It tricks people into having a quick thought about what you are describing. They generally take a little work to pull off, but the pay-off for you and the reader can be huge.
Videos: You can’t simply drop a 42-minute video in the middle of a blog post, but if you can make it clear that you are demonstrating something visual and the video is less than a minute, it can be a powerful choice. You’ve always got <video autoplay muted loop controls> as well to make it GIF-like.
Blocks of code: Technical blog posts are often about code. Don’t avoid code, embrace it. I love how Dan Abramov sprinkles in code blocks in blog posts not so much to demonstrate syntax and setup, but to make points. I’m going to recommend Embedded Pens as well, because they’re fully interactive demoes in addition to serving as code blocks.
Tables: Don’t forget about tabular data! Presenting information (particularly data or definitions) in a table makes it more understandable than it would have been any other way.
Collapsing sections: The <details>/<summary> elements make quick work of collapsible content. If you’ve got a large section of content that is good to be there but doesn’t need to be read by everyone, collapse it! Our reference guide of media queries for devices is a decent example of this in action.
Whatever you pick here, you should pick things that help enhance the points you’re making even if in some ways it feels like trickery. It’s trickery to help readability, and that’s a good thing.
My favorite technique? A little bit of design. Use design principals like spacing, color, and alignment to help the readability of posts. We even go so far as to art direct some posts where design can enhance the central point being made.
The point here isn’t to do away with walls of text altogether. Sometimes that’s exactly what’s needed because you’re asking a reader to deeply read a passage that they otherwise wouldn’t get what’s needed from the content. However, more often than not, a post can strongly benefit from some healthy use of white space.
Use an active voice
I find this one a little tricky to wrap my head around, but Katy Decorah has a great presentation about technical writing that explains this point in great detail. It’s kinda like using present tense and stating a point directly rather than passively.
Passive: „After the file is downloaded…” Active: „After you download the file…”
Passive: „The request is processed by the server.” Active: „The server processes the request.”
“Just” makes me feel like an idiot. “Just” presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. “Just” is a dangerous word.
There are plenty of others to avoid, which which I’ve written about before. Read the comments in that last link. Long story short: there are lots of words that do more harm than good in technical writing, not only because they can come across as preachy, but because they usually don’t help the sentences where they’re used. Try taking „just” out of any sentence. The sentence will still make sense without it.
SimplyClearlyJustOf courseEveryone knowsEasyHoweverSoBasicallyTurns outIn order toVery
Be mindful of your tone
Tone is concerned with how you say something in consideration of the context. For example, you wouldn’t deliver bad news to someone with a happy tone. The way you express yourself ought to be aligned with the situation.
This is our tone goal on this site:
Friendly. Authoritative. Welcoming. We’re all in this together. Flexible (nondogmatic about ideas). Thankful.
It’s worth pointing out that tone and voice are separate concepts. I like to think of voice as never changing (it’s your personality which is a part of who you are) while tone changes to suit the context. In other words, you can have a professional voice while communicating in a friendly tone.
I don’t think there is one true tone that is perfect for technical writing, but since the high-level goal of any technical writing is to help someone understand something complicated, you can use tone to help. A joke in the middle of a set of intricate steps is confusing. A bunch! of! excitement! about something might feel out of place or disingenuous, but being drab and lifeless is worse. I’d say if you’re writing under your own name, let’s feel a little bit of your personality as long as it’s not at the cost of clarity. If you’re writing under a brand, match what they have established whether it has been codified or not.
Careful about length
The general tendency in technical writing is to write too much rather than too little. Wade Christensen:
Whether trained by school assignments with word minimums or just uncritical, most of us write too much. Beyond approaching each draft with a ruthless cutting mentality, there are several ways to write short from draft one.
Word limits can help, even if they’re self-imposed.
I heard from a fledgling editor recently who struggled with his writers submitting posts with high word counts, so he suggested they keep it to 1000-1500 as a guideline and that seemed effective. This post is roughly double the high end there, for comparison.
The real solution, if the resources are there, is ruthless editing.
I personally don’t find that writing too long is the only issue. I’ve had just as many occurrences of writers going too short and not digging into the topic deep enough. I don’t like focusing on the length; I like focusing on the clarity of the delivery and usefulness of the content itself.
Side note: Breaking up a post into multiple parts (as separate posts in a series) is not a solution for posts that are too long. In fact, it can exacerbate the problem. Do that only if the different parts are thematically different and can stand alone without the other parts.
Don’t stop yourself from writing
There is an invisible force, built from fear, that keeps a lot of people away from technical blogging. „Meh, everybody already knows this,” you might think. (They don’t). „What if I’m wrong and someone calls me out?” (You aren’t wrong if what you’re doing is working for you.)
There can still be blockers even if you overcome those fears and start putting words to screen. Here’s Max Böck:
There is a thing that happens to me while writing. I start with a fresh idea, excited to shape it into words. But as time passes, I lose confidence.
The trick for Max is not to wait too long and to ignore feelings holding you back:
I’ll publish something as soon as I feel confident that all the important points I want to get across are there. I try to ignore the voice screaming “it’s not ready” just for long enough to push it online.
I think keeping drafts can be counterproductive. The problem is that, once something is a draft rather than a blog post, it’s likely to stay a draft and never become a blog post. And the longer something stays in draft, the less likely it is to ever see the light of day.
The chances that your writing helps someone is pretty high! Matthias Ott:
Even the smallest post can help someone else out there.
Think you’re too inexperienced? You’re probably not, but even if you were, a perspective from someone with less experience is still useful. Ali Spittel:
If you have a blog post that contains mostly correct information, or at least your interpretation of the topic, then you’re experienced enough. There are lots of excellent posts out there from the perspective of newbies, and they’re really important!
Fear is a real thing in writing and dealing with it can be debilitating. While it’s primarily geared toward creative writing, The War of Art by Stephen Pressfield is a good read to help break through the fear.
There is no one perfect style
We each have our own unique perspectives and writing styles. One writing style might be more approachable to some, and can therefore help and benefit a large (or even small) number of people in ways you might not expect.
Even if only one person learns something from your article, you’ll feel great, and that you’ve contributed — even if just a little bit — to this amazing community that we’re all constantly learning from.
Technical blog posts don’t have to be devoid of creativity. You could create a wonderful technical blog post that is an annotated chat room conversation between two developers learning from each other. Or a blog post that is a series of videos that build on each other.
The more introductory, the higher the bar
The web is saturated with beginner-rated and surface-level blog posts. There’s a sea of crash courses, 101s, and intros out there. You’ve gotta knock it out of the park if you want to stand out from the pack and be useful.
There is no particular change in tone necessarily for a beginner-focused post. You don’t need to do the equivalent of talking slowly or talking down. You only need to be clear, and clarity is valuable to readers at any skill level, not to mention appreciated by them as well. A very advanced programmer can and will appreciate the clarity in a technical blog post even if it’s something they already understand.
But the bar isn’t that high in general
You don’t need a decade of experience to write a blog post. I’d say it’s closer to a day of experience, a desire to write, and having something to say. I think you’d be surprised at how little you need to do to make a blog post stand out and be read. Put in some effort, make clear points, focus on readability, and you will do well.
I hope the advice in this post helps!
Abstraction is helpful, but real-world examples are sometimes better
It’s one thing to describe a high-level concept, and another to explain or illustrate how that concept applies to the real world. In technical writing, you’ll often be covering complex or hard-to-understand subjects, so it’s even more important to use a well-placed example or two to showcase why your topic matters, or how it relates to the real world.
I find myself pushing back on code that is too abstract more than I push back on code that is too focused on a real-world use case. I’d rather see ["Charles Adok", "Samantha Frederick"] than ["foo", "bar"] or [a, b] any day, but more importantly, what is then done with that data to make it feel like a relatable programming scenario.
But avoid real-world examples that come at the cost of clarity. If abstraction is useful to drive a complex point home without getting lost in the details, so be it.
Blogging opens doors
Everyone I’ve ever met who had ever actively blogged has said that blogging has had a positive impact on their career. Besides being a public demonstration of your ability to think and present ideas, it helps you understand things better. To teach is to learn.
I’d attribute my own blogging as the biggest contributor to any success I’ve had. Here’s Khoi Vinh, a designer ten times more successful than I’ll ever be:
It’s hard to overstate how important my blog has been, but if I were to try to distill it down into one word, it would be: “amplifier.”
You get better at what you do.
There is no way around it: practice makes you better. The expectations around practice are sometimes very clear and culturally ingrained. In order to get better at playing the piano, you take piano lessons and practice. We all know this. But people also say „Oh, I’m a terrible cook,” as if cooking as a skill is somehow fundamentally different than playing the piano and doesn’t require the same amount of learning and practice.
You get better at writing by writing more. That is, writing with stakes. Writing and then publicly publishing what you write such that people read it.
You can go to school for writing. You could get a writing coach. My thinking is nothing teaches better than writing often. Whatever it is you sink time into is what you end up getting good at. Is 10,000 hours a good framework for you? Go with it. Heck, I find even people that sit around watching a lot of TV end up being pretty damn good at watching TV.
Your voice alone < A story with context < Stories including others < Research and data along with stories including others
An article where you just say some stuff is OK. You’re allowed to say stuff.
But you can do better.
An article where you tell a true story about how something worked for you is better. Context! Now we can better understand where you are coming from when you say your stuff. Plus everybody likes a story.
An article where you combine that with quoting other people’s writing and stories is even better. Now you’re painting a larger picture and helping validate what you’re saying. Context and flavor!
An article where you combine all that with research and data is the best. Now you’re being personal, acknowledging a world outside yourself, layering in context, and avoiding being too anecdotal. Kapow! Now you’re writing!
Are you pitching?
Read what the site says about guest writing. Here’s ours.
Not to scare you off, but 90% of submissions are garbage. Maybe 75% is outright spam and another 15% are people that clearly didn’t read anything we had to say about guest posting and are way off base. I can usually tell from the quality of writing in the email itself if they’ll be a good guest blogger.
There probably is, but I don’t wanna link you off to tools I can’t vouch for. All I use is Dropbox Paper for collaborative writing because the sharing model is easy and allows for co-editing and commenting. Plus Grammarly because it catches a ton of mistakes as you go.
In advance of a recent podcast with the incredible technical writer and Smashing Magazine editor-in-chief Rachel Andrew, I gathered up a bunch of thoughts and references on the subject of technical writing. So many smart people have said a lot of smart things over the years that I thought I’d round up some of my favorite advice and sprinkle in my own experiences, as someone who has also done his fair share of technical writing and editing.
There is a much larger world of technical writing out there. My experience and interest is largely about web technology and blogging, so I’m coming at it from that angle and many of the people I quote throughout are in that same boat.
Picking something to write about
If you want to write for CSS-Tricks and you ask me what you should write about, I’m probably going to turn that question around on you. It’s likely I don’t know you well enough to pick the perfect topic for you. More importantly, what I really want you to write about is something that is personal and important to you. Articles rooted in recent excitement about a particular idea or technology always come out better than dictated assignments.
My best advice:
Write the article you wish you found when you googled something.
That said, I do maintain a list of ideas specifically for this site. Any writing can be done on assignment and sometimes that elicits the spark needed for something great and on-target for the audience of a site.
Write at the moment of learning
The moment you learn something is the best time to write. It’s fresh in your mind and you can remember what it was like before you understood it. You also understand what it takes to go from not knowing to knowing it. That’s the journey you need to take people on.
If you don’t have time, at least try to capture the vibe wherever you save your ideas. Don’t just write down „dataset.” Write down some quick notes like, „I didn’t realize DOM elements had a .dataset property for getting and setting data attributes. I wonder if it’s better to use that than getAttribute.” That way, you’ll be able to reload that realization in your brain when you revisit the idea.
Here’s some advice Rachel shared that I don’t see taken advantage of nearly enough:
There is a sweet spot for writing technical posts and tutorials. Write for the professional who hasn't had time to learn that thing yet, and link it back to things they already know. For example explaining a modern JS technique to someone who knows jQuery.
Tell me about how this new framework relates to Backbone. Tell me how this CMS relates to WordPress. Tell me how some technology connects to another technology that is safe to assume is more widely understood.
Technology changes a lot, but what technology does doesn’t change all that much.
Careful with that intro
The main comment I add on tutorials I review is to ask for an intro that describes what the tutorial is about. I'm 600 words in and still don't know what the tutorial is about and who it is for. #writing
Not getting to the point right at the top of technical articles is a dang epidemic. The start of a technical article is not the time to wax poetic or drop some cliché light philosophy like, „Web design sure has changed a lot.” You don’t have to be boring, but you do need to tell me what this article is going to get into and who it is for.
“Does the title make the article sound interesting?” If the title interests a reader, they’ll typically read the intro and decide, “Is it worth my time reading the whole thing?” A common mistake I see in a lot of technical posts is either too much introduction or, alternatively, far too little.
A single well-written paragraph can set the stage for a technical blog post.
Careful with the title, too
I remember a conversation from years ago with content strategist Erin Kissane where she strongly advised me to choose boring titles for everything. Not just the title of blog posts, but for everything, including the names of sections, tags, and even subheadings within posts.
Here’s the thing with boring: it works. Boring isn’t the right word either; it’s clarity. The world is full of clickbait, and maybe that’s effective in some genres, but technical blogging isn’t one of them.
A terrible version of the same: Build a web app with modern technologies in 30 minutes!
What’s a web app? What technologies? What’s modern about them? What’s with the weird time limit?
SEO matters and Margaret’s article is going to do a lot better in both the short and long term with that clear title.
The outro
Ben Halpern says that the next most important thing after the intro is:
[…] the last paragraph.
People don’t read top-to-bottom the moment when they arrive, so there is a good chance it’s the second paragraph people read. Personally, I find the beginning a lot more important than the ending, but there is a certain art to the ending as well.
A lot of people just <h2>Conclusion</h2> and write a few words about what was just went over. Honestly, I don’t hate that. It falls into this time tested pattern:
Tell ’em what you’re gonna tell ’em
Tell ’em
Tell ’em what you told ’em
That helps your message sink in and brings things full circle. Technical blogging isn’t terribly different from marketing in that sense. You’re trying to get people to understand something and you’re using whatever tricks you need to to get the job done. A little repetition is a classic trick.
[…] the wall of text can be easily be made less intimidating and appear much more visually appealing through the use of visual elements that break it up. The easiest is to simply place section subheadings throughout your post.
I agree: subheadings are probably the easiest and most powerful trick for scannability.
Other methods:
Lists: Like what I’m doing right now! I didn’t have to use a list. Paragraphs might have worked as well, but a list makes contextual sense here and is probably tricking some of you into reading this. Or at least scanning it and getting some key points in the process.
Images: Please make them relevant and contextual. Skip the funny GIF. Screenshots are often great in a technical context because they provide a visual to what might otherwise be a difficult concept to explain. I like Unsplash for thematic imagery, too, but you can do better than a random picture of trees, a woman drinking coffee, or a random rack of servers.
Illustrations: The abstract nature of an illustration is your friend. It tricks people into having a quick thought about what you are describing. They generally take a little work to pull off, but the pay-off for you and the reader can be huge.
Videos: You can’t simply drop a 42-minute video in the middle of a blog post, but if you can make it clear that you are demonstrating something visual and the video is less than a minute, it can be a powerful choice. You’ve always got <video autoplay muted loop controls> as well to make it GIF-like.
Blocks of code: Technical blog posts are often about code. Don’t avoid code, embrace it. I love how Dan Abramov sprinkles in code blocks in blog posts not so much to demonstrate syntax and setup, but to make points. I’m going to recommend Embedded Pens as well, because they’re fully interactive demoes in addition to serving as code blocks.
Tables: Don’t forget about tabular data! Presenting information (particularly data or definitions) in a table makes it more understandable than it would have been any other way.
Collapsing sections: The <details>/<summary> elements make quick work of collapsible content. If you’ve got a large section of content that is good to be there but doesn’t need to be read by everyone, collapse it! Our reference guide of media queries for devices is a decent example of this in action.
Whatever you pick here, you should pick things that help enhance the points you’re making even if in some ways it feels like trickery. It’s trickery to help readability, and that’s a good thing.
My favorite technique? A little bit of design. Use design principals like spacing, color, and alignment to help the readability of posts. We even go so far as to art direct some posts where design can enhance the central point being made.
The point here isn’t to do away with walls of text altogether. Sometimes that’s exactly what’s needed because you’re asking a reader to deeply read a passage that they otherwise wouldn’t get what’s needed from the content. However, more often than not, a post can strongly benefit from some healthy use of white space.
Use an active voice
I find this one a little tricky to wrap my head around, but Katy Decorah has a great presentation about technical writing that explains this point in great detail. It’s kinda like using present tense and stating a point directly rather than passively.
Passive: „After the file is downloaded…” Active: „After you download the file…”
Passive: „The request is processed by the server.” Active: „The server processes the request.”
“Just” makes me feel like an idiot. “Just” presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. “Just” is a dangerous word.
There are plenty of others to avoid, which which I’ve written about before. Read the comments in that last link. Long story short: there are lots of words that do more harm than good in technical writing, not only because they can come across as preachy, but because they usually don’t help the sentences where they’re used. Try taking „just” out of any sentence. The sentence will still make sense without it.
SimplyClearlyJustOf courseEveryone knowsEasyHoweverSoBasicallyTurns outIn order toVery
Be mindful of your tone
Tone is concerned with how you say something in consideration of the context. For example, you wouldn’t deliver bad news to someone with a happy tone. The way you express yourself ought to be aligned with the situation.
This is our tone goal on this site:
Friendly. Authoritative. Welcoming. We’re all in this together. Flexible (nondogmatic about ideas). Thankful.
It’s worth pointing out that tone and voice are separate concepts. I like to think of voice as never changing (it’s your personality which is a part of who you are) while tone changes to suit the context. In other words, you can have a professional voice while communicating in a friendly tone.
I don’t think there is one true tone that is perfect for technical writing, but since the high-level goal of any technical writing is to help someone understand something complicated, you can use tone to help. A joke in the middle of a set of intricate steps is confusing. A bunch! of! excitement! about something might feel out of place or disingenuous, but being drab and lifeless is worse. I’d say if you’re writing under your own name, let’s feel a little bit of your personality as long as it’s not at the cost of clarity. If you’re writing under a brand, match what they have established whether it has been codified or not.
Careful about length
The general tendency in technical writing is to write too much rather than too little. Wade Christensen:
Whether trained by school assignments with word minimums or just uncritical, most of us write too much. Beyond approaching each draft with a ruthless cutting mentality, there are several ways to write short from draft one.
Word limits can help, even if they’re self-imposed.
I heard from a fledgling editor recently who struggled with his writers submitting posts with high word counts, so he suggested they keep it to 1000-1500 as a guideline and that seemed effective. This post is roughly double the high end there, for comparison.
The real solution, if the resources are there, is ruthless editing.
I personally don’t find that writing too long is the only issue. I’ve had just as many occurrences of writers going too short and not digging into the topic deep enough. I don’t like focusing on the length; I like focusing on the clarity of the delivery and usefulness of the content itself.
Side note: Breaking up a post into multiple parts (as separate posts in a series) is not a solution for posts that are too long. In fact, it can exacerbate the problem. Do that only if the different parts are thematically different and can stand alone without the other parts.
Don’t stop yourself from writing
There is an invisible force, built from fear, that keeps a lot of people away from technical blogging. „Meh, everybody already knows this,” you might think. (They don’t). „What if I’m wrong and someone calls me out?” (You aren’t wrong if what you’re doing is working for you.)
There can still be blockers even if you overcome those fears and start putting words to screen. Here’s Max Böck:
There is a thing that happens to me while writing. I start with a fresh idea, excited to shape it into words. But as time passes, I lose confidence.
The trick for Max is not to wait too long and to ignore feelings holding you back:
I’ll publish something as soon as I feel confident that all the important points I want to get across are there. I try to ignore the voice screaming “it’s not ready” just for long enough to push it online.
I think keeping drafts can be counterproductive. The problem is that, once something is a draft rather than a blog post, it’s likely to stay a draft and never become a blog post. And the longer something stays in draft, the less likely it is to ever see the light of day.
The chances that your writing helps someone is pretty high! Matthias Ott:
Even the smallest post can help someone else out there.
Think you’re too inexperienced? You’re probably not, but even if you were, a perspective from someone with less experience is still useful. Ali Spittel:
If you have a blog post that contains mostly correct information, or at least your interpretation of the topic, then you’re experienced enough. There are lots of excellent posts out there from the perspective of newbies, and they’re really important!
Fear is a real thing in writing and dealing with it can be debilitating. While it’s primarily geared toward creative writing, The War of Art by Stephen Pressfield is a good read to help break through the fear.
There is no one perfect style
We each have our own unique perspectives and writing styles. One writing style might be more approachable to some, and can therefore help and benefit a large (or even small) number of people in ways you might not expect.
Even if only one person learns something from your article, you’ll feel great, and that you’ve contributed — even if just a little bit — to this amazing community that we’re all constantly learning from.
Technical blog posts don’t have to be devoid of creativity. You could create a wonderful technical blog post that is an annotated chat room conversation between two developers learning from each other. Or a blog post that is a series of videos that build on each other.
The more introductory, the higher the bar
The web is saturated with beginner-rated and surface-level blog posts. There’s a sea of crash courses, 101s, and intros out there. You’ve gotta knock it out of the park if you want to stand out from the pack and be useful.
There is no particular change in tone necessarily for a beginner-focused post. You don’t need to do the equivalent of talking slowly or talking down. You only need to be clear, and clarity is valuable to readers at any skill level, not to mention appreciated by them as well. A very advanced programmer can and will appreciate the clarity in a technical blog post even if it’s something they already understand.
But the bar isn’t that high in general
You don’t need a decade of experience to write a blog post. I’d say it’s closer to a day of experience, a desire to write, and having something to say. I think you’d be surprised at how little you need to do to make a blog post stand out and be read. Put in some effort, make clear points, focus on readability, and you will do well.
I hope the advice in this post helps!
Abstraction is helpful, but real-world examples are sometimes better
It’s one thing to describe a high-level concept, and another to explain or illustrate how that concept applies to the real world. In technical writing, you’ll often be covering complex or hard-to-understand subjects, so it’s even more important to use a well-placed example or two to showcase why your topic matters, or how it relates to the real world.
I find myself pushing back on code that is too abstract more than I push back on code that is too focused on a real-world use case. I’d rather see ["Charles Adok", "Samantha Frederick"] than ["foo", "bar"] or [a, b] any day, but more importantly, what is then done with that data to make it feel like a relatable programming scenario.
But avoid real-world examples that come at the cost of clarity. If abstraction is useful to drive a complex point home without getting lost in the details, so be it.
Blogging opens doors
Everyone I’ve ever met who had ever actively blogged has said that blogging has had a positive impact on their career. Besides being a public demonstration of your ability to think and present ideas, it helps you understand things better. To teach is to learn.
I’d attribute my own blogging as the biggest contributor to any success I’ve had. Here’s Khoi Vinh, a designer ten times more successful than I’ll ever be:
It’s hard to overstate how important my blog has been, but if I were to try to distill it down into one word, it would be: “amplifier.”
You get better at what you do.
There is no way around it: practice makes you better. The expectations around practice are sometimes very clear and culturally ingrained. In order to get better at playing the piano, you take piano lessons and practice. We all know this. But people also say „Oh, I’m a terrible cook,” as if cooking as a skill is somehow fundamentally different than playing the piano and doesn’t require the same amount of learning and practice.
You get better at writing by writing more. That is, writing with stakes. Writing and then publicly publishing what you write such that people read it.
You can go to school for writing. You could get a writing coach. My thinking is nothing teaches better than writing often. Whatever it is you sink time into is what you end up getting good at. Is 10,000 hours a good framework for you? Go with it. Heck, I find even people that sit around watching a lot of TV end up being pretty damn good at watching TV.
Your voice alone < A story with context < Stories including others < Research and data along with stories including others
An article where you just say some stuff is OK. You’re allowed to say stuff.
But you can do better.
An article where you tell a true story about how something worked for you is better. Context! Now we can better understand where you are coming from when you say your stuff. Plus everybody likes a story.
An article where you combine that with quoting other people’s writing and stories is even better. Now you’re painting a larger picture and helping validate what you’re saying. Context and flavor!
An article where you combine all that with research and data is the best. Now you’re being personal, acknowledging a world outside yourself, layering in context, and avoiding being too anecdotal. Kapow! Now you’re writing!
Are you pitching?
Read what the site says about guest writing. Here’s ours.
Not to scare you off, but 90% of submissions are garbage. Maybe 75% is outright spam and another 15% are people that clearly didn’t read anything we had to say about guest posting and are way off base. I can usually tell from the quality of writing in the email itself if they’ll be a good guest blogger.
There probably is, but I don’t wanna link you off to tools I can’t vouch for. All I use is Dropbox Paper for collaborative writing because the sharing model is easy and allows for co-editing and commenting. Plus Grammarly because it catches a ton of mistakes as you go.
I really enjoyed this interview with Jeremy Keith on the state of the web, how things have changed in recent years and why he’s a mix of optimistic and nervous for the future.
One thing that caught my attention during the interview more than anything was where Jeremy started discussing how folks think that websites are pretty crummy in general. This reminded me that I cannot count the number of times when someone has said to me “ah, I can’t view this website on my phone.”
We have websites that aren’t responsive! We have websites that litter the UI with advertisements and modals! And we have websites that are slow as all heck just when we need them the most!
Of course folks are going to start complaining about the web and working around them if they find that this is the case. I’ll even catch myself sending an email to myself when I know that the mobile experience is going to be crummy. Or I’ll Instapaper something because the design of the website is particularly difficult to read. Remember, Reader Mode is the button to beat.
My quick thought on this is that we shouldn’t become sour and pessimistic. We should roll up our sleeves and get to work because clearly there’s much left to do.
I really enjoyed this interview with Jeremy Keith on the state of the web, how things have changed in recent years and why he’s a mix of optimistic and nervous for the future.
One thing that caught my attention during the interview more than anything was where Jeremy started discussing how folks think that websites are pretty crummy in general. This reminded me that I cannot count the number of times when someone has said to me “ah, I can’t view this website on my phone.”
We have websites that aren’t responsive! We have websites that litter the UI with advertisements and modals! And we have websites that are slow as all heck just when we need them the most!
Of course folks are going to start complaining about the web and working around them if they find that this is the case. I’ll even catch myself sending an email to myself when I know that the mobile experience is going to be crummy. Or I’ll Instapaper something because the design of the website is particularly difficult to read. Remember, Reader Mode is the button to beat.
My quick thought on this is that we shouldn’t become sour and pessimistic. We should roll up our sleeves and get to work because clearly there’s much left to do.
