Better specifications for the sake of the Web

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.