Thinning the W3C boilerplate for specs

Pretty much every W3C document opens with about a page and a half of redundant legalese preamble (likely stemming from its academic origins). Sometimes, this preamble changes based on when the document was written, making it both redundant and obsolete.

I propose that we (where “we” is some vague W3C-adjacent group of web developers of no specific group membership) lower the barriers to writing and maintaining specs by stripping off this dead weight, one way or another:

Abstracts

The idea of writing an abstract for a W3C spec seems to be some kind of vestigial organ from the days where W3C papers would be written alongside articles on particle physics in CERN research journals. Realistically, anybody who comes across a web spec is going to have some familiarity with it in context, and doesn’t need an executive summary beyond what they can glean from the title and introduction. Axing this would make specs easier to write, and quicker to read.

“Status of This Document”

This is just a long-form statement that old documents can be superseded by new ones, which is obvious to anybody who has ever worked with any kind of documented rules, anywhere. It’s completely redundant with the block that already appears at the top of all W3C-published documents that already includes “This version”, “Latest published version”, “Latest editor’s draft”, “Previous version”, “Version history”, and “Commit History”.

It includes a bunch of rules about how the document should be read that’d best be hyperlinked from somewhere else, ie. on a wiki page that describes how the W3C (and the greater web ecosystem) generally proceeds. It also includes some directives regarding contributing and feedback, which are redundant to the “Participate” heading at the top of the page.

It also includes some legal disclaimers like the document’s accordance with the W3C Patent Policy and Process Document. Just tack that stuff onto the end of “W3C liability, trademark and document use rules apply.”

The useful thing to know about a document’s status that should be included here, but isn’t, is how it’s been adopted since its introduction, by vendors (for gauging current support) and content authors (for gauging future support).

For what it’s worth, we do have a side project for that.

The first iteration for 2016 is limited to style sheets due to other priorities but the goal is to completely redesign the W3C technical reports. For 2016, you can see the results in some of the editor’s drafts already, like the CSS ones, or some of the webperf ones. If everything goes according to plan, we should be set for the switch of the new style sheets on February 1. Not the general cleanup you’re looking for but a start.

You’ll see more changes in 2017. Some early discussion of that happened last October. You can see some very early ideas.

The Abstract section is the first thing I read in a spec and I find it to be an useful summary of the spec, generally speaking. I don’t see how removing it would make a difference for the better.

The part about familiarity is not correct; specs introduce new concepts, which the reader cannot be familiar with, when they encounter a spec for the first time.

In my opinion, 1-paragraph summaries are always welcome, whether it’s a spec, a blog post, a documentation page, etc.

Agreed, the Abstract is actually really useful, as least when decently written. It’s a small, useful intro to the spec. (The Introduction section, when well written, introduces you to all the major concepts in the spec in a slightly longer form.)

I would certainly support making changes so that the parts of the document that are more frequently read are more prominently styled/come first, but I wouldn’t want to get rid of the SoTD section altogether, as I find it very useful. People who aren’t intimately familiar with W3C Process also read W3C specs, and often they have lots of questions about the level of stability of a document, how it’s changed, how they can send feedback and the like. And when I read documents from other governance-style groups that don’t have such texts at the beginning of their documents, I’m often confused and have to ask people involved to determine the actual status.

Maybe we could turn the boilerplate paragraphs into shorter sentences, with links to an accessible version of W3C documentation that explains document status and participation in more detail.

Note that this stuff is managed in a different group:

The requirement for a status section is largely defined in the W3C Process document section 6.2.1, with some practical stuff defined by the W3C Publication Rules - known as “pubrules”.

The Process document is agreed between W3C and its Members, and the evolution is managed by the Advisory Board working in the Revising W3C Process community group which anyone can join.

Pubrules is maintained by the W3C Team, but there isn’t any obvious info there about where to request changes - I’ll ask about that, or @plehegar might answer first…

Yes, I agree that would be useful. There is nothing to stop people doing it, although I suspect a link is better since the implementation status sometimes changes more rapidly than the document, isn’t always well-maintained, and can get unwieldy as part of the introductory text…

With the recent deprecation of the old pubrules engine, Pubrules is now managed at

We don’t have however an automatic way to check if the abstract is decently written so we simply check the presence of text but not how useful it is.