Thoughts on Web Specs and Docs
Fershad Irani posted a question1 asking about how folks work with the standard and guidelines from the W3C Web Sustainability Guidelines2. These are a few quick notes in response.
- My only real experience looking at web spec documents is with the HTML Living Standard3. I rarely go to it though. Most of the time I'm at MDN4.
- I'd describe the reason being because the spec is super technical while MDN is more prose.
- The main time I go to the HTML Living Standard specs is when I'm looking up something for a post. (e.g. what characters are allowed as attribute names). Basically, I'm looking for a specific piece of info instead of just reading for general info.
- I didn't know the Web Sustainability Guidelines existed until Fershad's post. I'm not surprised they exist. It just never occurred to me to look.
- As Fershad mentions: There are 92 guidelines at the moment (with 254 associated success criteria). I wouldn't even know where to begin.
- What are the top three things I need to know?
-
The content of the introduction is hidden behind a details element. I missed it the first time I looked at it. The first thing my eyes went to is this opening paragraph for section 1.1: Background on WSG
Web Sustainability Guidelines (WSG) define how to make web products and services more sustainable for people and the planet. Web sustainability addresses more than just environmental issues [VARIABLES]; intersectional issues such as accessibility, privacy, and security can impact the sustainability of a project. We have an overview of web sustainability if you would like to learn more about the subject. The Interest Group considers that WSG incrementally advances web sustainability in numerous areas, but underscores that not all environmental improvements are met by these guidelines, as sustainability is an emerging field and research gaps may exist in certain areas. These guidelines may make digital products and services more performant, usable, and improve other metrics for end-users as a by-product of being sustainable. WSG may also be helpful to comply with existing and upcoming worldwide regulatory frameworks, reporting schemes, and compliance requirements (laws and policies).
It's a huge paragraph with logs of long words. That makes my eyes glaze over.
-
Phrases like intersectional issues sound overly academic or corporate or like legalese.
Overall, it feels like the doc isn't for me. And, like it's a spec and specs have a specific form.
But, if the general goal is to get me to think about sustainability, it's unlikely to happen here.
As before, I go to specs when I'm after a specific thing that I need an answer to. If I don't even know to ask the question I'll never end up on it.
-
The top level descriptions for items are nice, e.g.
Use distraction and clutter-free design, showing the visitor only what they need without interruptions or wasted resource consumption.
In the 2.6 Minimize non-essential content, interactivity, or journeys section
But, that's immediately followed by the various Success Criterion. That feels like combining two types of content. The top level description is great for a list, but the other content feels like noise if I'm just trying to browse.
- That gives me an overall feeling that the doc is trying to speak to multiple audiences that are operating are views things through different lenses that don't fully overlap.
-
I really like the idea that there are four types of documentation: tutorials, how-to guides, technical reference and explanation.
- Thinking about it in that light, the docs are mostly Technical Reference but have a lot of Explanation thrown in. For example, the intro to section 2. User Experience Design is a solid explanation. Then, the sub sections get into the all the different Success Criterion points that are technical reference.
- It feels weird to have a "Plain language summary of User Experience Design" directly under the opening prose. This goes again to trying to reach two audiences. In this case, by literally going over the same content in two different ways.
-
I'd cut down on the prose. For example, this is the opening of the section:
If you are creating content and systems designed for users, then whether you know it or not, you are working in user experience (UX).
You can drop that entirely and use the next sentence which is a much stronger opener.
Good user experience reduces time and resources wasted on the journey.
-
I'm a fan of the traditional writing advice: Use fewer words5.
For example, if I were going to extract and create a more prose driving explanation of the Intro to section 2 I'd do something like this:
The visual design and presentation of information has a significant impact on web sustainability. Ensuring accessibility and fast load times amplifies the positive impacts of your content. Social inclusion improves along with your SEO and the number of users who successfully complete e-commerce transactions.
The principals for achieving experience design success are:
- Regular review of user and internal organizational needs.
- A focus on clear information architecture and navigation.
- Optimizing content and assets.
See Section 2 - User Experience Design for detailed success criteria.
-
One of the reasons I find MDN so compelling is the examples. Give me more of the practical than the theoretical I get from the explanation parts of the spec.
Basically "Show, don't tell"
- Also, videos would be great for that. Meet the people where they are.
Finally, this is a hugely tricky batch of content to deal with. Mostly, because it's so huge itself. Credit to the folks who are working to improve the mountain of material.
-a
Endnotes
Another related idea is that there isn't a "one-stop-shop" for specs and guidelines. MDN is the closest I've seen, but it's limited. It would be great if there was a home page for getting started with all this stuff.
(Of course, there's probably a hundred of them already and adding another one would be like XKCD 927.)
Some of these comments are harsh. It's clear that lots of folks put a lot of work into this. I'm not ripping on the specs out of spite. It makes me uncomfortable to criticize other folks work, but if the goal is to make it better it's a necessary part of the process.
I first saw the question from Fershad on the ShopTalk Show Discord. It's a solid place for web related discussion and general conversations around tech, gear, etc... It's a membership style discord. See Patreon for details.
Footnotes
The original post that kicked off this one.
And yes, I realize that's not evident here. You've have to forgive me for using more words as these are general notes instead of a fully editing piece :-)