This post is co-authored by Virginie Galindo and Richard Ishida, currently working hand in hand to promote better wide review of W3C specifications.
The Open Web Platform is getting increased traction from new communities and markets thanks to the attractive portability and cross-device nature of its specifications – characteristics which are strengthened by horizontal and wide reviews. But the increase in specifications compounds a growing difficulty when it comes to ensuring that specs are adequately reviewed.
The number of specifications initiated in W3C is increasing every year. That growth is welcome, but we want to avoid ending up with series of parallel technologies that lack coherence. That is one reason the W3C is putting efforts into a campaign to ensure that all specifications will benefit from wide review. Reviews, from the public and from experts, to ensure that all features and specifications create a trusted and sustainable Web for All.
Reviewing a specification is not an easy task, especially when a reviewer does so on a voluntary basis, squeezing it in between two or more high value tasks. One can appreciate that a prerequisite for asking for wide review is that the W3C specification is readable by the non-specialist who is affected by the features it addresses.
Think also about the scenario where an accessibility expert is reviewing an automotive API, or an internationalization expert is reviewing a brand new CSS feature, or a security expert is reviewing a new protocol. The spec needs to be understandable to these non-domain experts.
The basics dictate that a specification should contain use cases and vocabulary sections, that it should rely on plain English, etc. But you should also bear in mind that most reviewers have to produce feedback in a limited time, with limited experience, and having perhaps only read the spec through a couple of times.
Here are few additional tricks for specification editors to keep your reviewer on track.
Summarize algorithms. Parts of the spec that are expressed as algorithmic steps can make it difficult to grasp the fundamental lines of what is being proposed (and sometimes it even takes a while to ascertain that it’s not anything particularly complicated in the end). Adding a summary of what the algorithm does can make a huge difference for those needing to get the bigger picture quickly.
Do not fragment information (or do use signage). When information is dispersed around the document to such an extent that one has to hold the whole spec in one’s brain to be able to find or piece together information on a particular topic, this is not good for reviewers. If it’s possible to reduce the fragmentation, that would be helpful. If not, please add plenty of signage, so that it’s clear to people who don’t hold the whole spec in their brain where they need to look for related information.
Use diagrams. Sometimes a large amount of textual information could be expressed very quickly using a railroad diagram, an illustration, or something similar. No-one wants to wade through (often pages of) tedious detail when reading a spec when a diagrammatic approach could summarise the information quickly.
Give examples. Examples are extremely useful and help people grasp even complex ideas quickly. Please use as many as you can. If you are describing a format, include an example of that format which includes most of the quirks and kinks that need to be described. If you are describing a result, show an example of the code and the result. If you are describing something you need the reader to visualise, use a picture. Etc. Basically, please use as many examples as possible.
Ensuring that W3C specifications are readable leads to better reviews and feedback. Better reviews and feedback lead to a more coherent Web and greater support for universal access and interoperability. These latter, in return, lead to greater attractiveness of W3C specifications for new communities and markets.
3 thoughts on “Better specifications for the sake of the Web”
I am in total agreement with this agenda, especially the parts about specifications using plain language and being reviewed by peripheral eyes.
HTML5 has been a disappointment for me. Call it cognitive dissonance, but I expected a better specification from a group of editors with claims of academic expertise.
Reading the HTML5 specification (and I have read it in so many different ways), I can’t help but to visualize the desolate remains of a civil war where no winners have emerged.
The HTML5 specification is a complete mess: rushed to Recommendation in order to beat the other side from getting theirs out first. As a result, HTML has been fractured. No politically-driven speeches can or will change this fact.
HTML5 is a core technology of the web. This particular specification should have been written, edited, and reviewed by representatives from all interests of the web. Heck, even teachers at the primary education level should have been invited to review it for the sake of those young citizens who will eventually use it.
I feel that what is being proposed in this article is a necessary consideration for the W3C. Break the web and rebuild it. How long can a web that is held together with tape and bandages remain standing?
Go back to the previous agenda of moving the web towards XML. Do not accommodate lazy web authors who want to claim being professionals, but code pages in an unprofessional manner and, thus, rely on browsers to fix their mess.
Specify how the web should be or how the web actually is, but don’t mix the two. Heck, create two lanes of specifications to address each issue if need be, but be specific in the specifications.
There is no doubt the W3C consists of a brilliant think tank, but politics, like power, corrupts absolutely. Don’t be afraid to make children take their vitamins as XML is indeed a much needed vitamin for the web.
I am as high as a kite
Comments are closed.