[Geoff]: There’s been a recent resurgence in the Document Outline debate, though this time with a (sorta) resolution. The original idea that we could have an outline algorithm that allows us to use <h1> as a generic heading element anywhere on a page was promising.
There were flaws though. Amelia Bellamy-Royds explored all the problems caused by what she called the “Document Outline Dilemma” in 2017.
But the Document Outline Algorithm was never implemented, as Adrian Roselli told us way back in 2013 and again in 2016:
Disregarding the fact that it was never part of the final W3C spec, that the spec had a warning for three years, that nobody considered the algorithm a bad idea, that screen readers had nothing to do with it, and that browsers not implementing it is different from correctly implementing it, there is one statement that belies the issue at hand.
“There Is No Document Outline Algorithm”
[…] It presumes that the specification’s primary benefactors are developers when in reality it is about users. It also presumes that it is acceptable to give developers advice (that harms some users) that has never been supported.
Fast-forward 6.75 years, and the algorithm has officially been removed from the WHATWG Living Standard. Bruce Lawson called it out in his too-hard-to-not-click article titled, “Why the HTML Outlining Algorithm was removed from the spec – the truth will shock you!” He goes on to say:
Here comes the shocker: it has never worked. No web browser has implemented that outlining algorithm. If you used
<h1>across your documents, it has always had a flat structure. Nothing has been taken away; this part of the spec has always been a wish, but has never been reality.
Geez Louise! It’s bizarre as heck that a standard we are all supposed to follow for best practices never reflected the reality of how browsers work for so many years. If you’ve ever stumbled (like I have) when asked whether it’s OK to have more than one <h1> on a page, this is why and you can rest easier knowing a line has been drawn in the sand for now.
So, the flat structure we’ve always had? Yeah, keep using that. But definitely dig into those linked posts because there is much more nuance and context in the details and comments.
Writing is a developer’s job, too
That’s what Eluda says in a pretty darn comprehensive collection of writing advice and tips aimed directly at developers. Sure, you may not be responsible for your company’s content style guide, but there’s still plenty of overlap between writing and development.
We’re talking about everything from writing code comments all the way to full-blown documentation, and Eluda gets into nitty-gritty grammar stuff that’ll sharpen your skills and walk you through best practices with plenty of examples.
Semi-related: Kitty Giraudel has a nice new set of guidelines for effectively asking for help.
React Hooks you might not use everyday
You’re probably well aware of the hits, like useEffect and useState. Blessing Ene Anyebe picks out five React Hooks that may be “new” to you.
While all React hooks are interesting in their own way, there are five of them that I really want to show you because they may not pop up in your everyday work — or maybe they do and knowing them gives you some extra superpowers.
That includes useReducer, useRef, UseImperativeHandle, useMemo, and useCallback. Blessing not only does a great job describing what they do, but has handy demos and examples for how to, ahem, use them.
What does your desk say about ya?
I recently moved from California to Colorado and have been wrestling boxes to set up my new office. As I was doing it, I got a little sentimental and starting think about about all the various “offices” I’ve had. As fate might have it, Jim Nielsen published some thoughts around offices. He quotes sage advice from Stephen King’s book, On Writing, to not make a desk the center of life:
Put your desk in the corner, and every time you sit down there to write, remind yourself why it isn’t in the middle of the room. Life isn’t a support-system for art. It’s the other way around.
So, I spent some time reflecting and trying my best to do just that.
What about you? How is your desk arranged? Is there anything about your office that says something about you as a person?
It’s 1997 and you want to build a website…
Jay Hoffman was on the ShopTalk podcast recently, riffing with Chris and Dave on the web history. Right after the episode was published, Jay posted a follow-up that wades through the options for building a website back in 1997. Funny enough, the options themselves aren’t all that different form today: DIY or let someone else do it for you!
But say it’s 1997 you want to do it yourself. It’s not like there’s MDN for advice. Or freeCodeCamp for learning. What do you do? Well, maybe read a book on the subject, like Bebo White’s HTML and the Art of Authoring for the World Wide Web or Laura Lemay’s Teach Yourself Web Publishing with HTML in a Week.
OK, not the DIY type? Here’s a web agency you could reach out to for some help.
stroke-dasharray patterns be weird
The property accepts any number of values to set the length of dashes and gaps on an SVG stroke:
line {
stroke-dasharray: 5;
}But more specifically, what we’re really setting there is a pattern of dashes and gaps. That 5 value isn’t just the length of the dashes, but the length of the gaps between them as well. So, what we’re really saying is this:
line {
stroke-dasharray: 5 5; /* Dashes: 5 units; Gaps: 5 units */
}That’s what happens any time we declare an odd number of stroke-dasharray values. For example, a three-value pattern like this:
line {
stroke-dasharray: 5 10 15;
}…is really equivalent to this:
line {
stroke-dasharray: 5 10 15 5 10 15;
}I have a full post for you on it with a big ol’ hat tip to reader Joshua Dance for writing in with the clarification.
Minimal Social Markup
Chances are you have worked with “social markup” before. You know, the metadata in <head> that is supposed to make pretty cards when sharing links.
<head>
<meta property="og:title" content="The blue sky strategy" />
<meta property="og:description" content="Less clouds, more blue" />
<meta property="og:image" content="/sky-with-clouds.jpg" />
<!-- ... -->
</head>Jens Oliver Meiert digs in and explains how he arrived at what he thinks is the minimum markup to make it all work. He documents how he had to wrestle with inconsistent standards and implementations of the Open Graph protocol to arrive at his final code, all the way down to quite marks.
One problem relates to a pretty consistent inability of messenger apps (!) to retrieve social images, if the respective attributes aren’t put in quotes—an odd bug given that other information can be pulled.
That’s it for now! We’re hoping to keep this dear newsletter going on a regular basis like before. It’ll probably take a little ramping up though. In the meantime, thanks for hanging out — it feels good to be “back.”
🧡
