Restyle W3C: Towards a More Usable Spec Template

Discussion is on the Specification Production Mailing List (please include [Restyle] in the subject line). See also the TR Design project on GitHub, which holds our current styles.

Scope

This effort is about redesigning the W3C spec templates--reworking our content formatting, and tying it all together with a new visual style. The goal is to re-envisioning what the spec template can be, to make it more usable and to bring actual content above the fold. Everything about the spec template is in scope: HTML, CSS, boilerplate content.

This effort is not about adding new functionality to our specification format, such as incorporating test results, issue tracking, or other systems. It is only about reworking how we present the spec content in static (hypertext and printed) form.

Boilerplate and Layout

This branch of the Restyle effort is about redesigning the content of the W3C spec template.

The first step is identifying what information needs to be in the template. The second step will be organizing, ordering, marking up, and laying out that information. See Karl Dubost’s comparison with boarding passes for what we're aiming at here.

dsinger adds:

We should be able to know a few axes “at a glance”:

is this a work-in-progress, or “done”?

is this a specification or something else (Rec or not)?

what is the consensus level; is this a W3C product or WG (or individual)?

Modulations of these can, I think, be reasonably described in the SOTD; what variety of note, documentation of jointly-developed documents, how “not finished” is a draft, and so on.

Visual Design

This part is about the visual design of the spec: the look and feel of the specs and the layout and styling of the header, of metadata, etc. It's dependent on the boilerplate content and layout being stabilized.

Here's a critique of a past effort that explains some of the considerations that make the design requirements for W3C specifications unusual.

Personality of the design: authoritative, approachable, timeless (10-year design lifespan), modern (computer technology field, not historical literature)

Readability

This part is about the typography of the specs: the styling of headings, lists, paragraphs, tables, examples, notes, code snippets, IDLs, etc. It integrates with the overall Design aspect. We did a first pass in 2016. We'll need another one in 2021 to adapt to the 2020_website_redesign.

[See existing documentation of our markup conventions.]

General Requirements

Both perusable (deeply-focused reading, by targetted section or from top to bottom) and scannable (skim to find relevant bits of info)
Accessible
Cross-platform, cross-device, & responsive
Beautifully and usably printable
Graceful degradation down to zero JS and/or zero CSS
Top quality, correct/readable/maintainable HTML and CSS, following best practices

User Research

In Spring 2018, W3C collaborated with the Jefferson University Interaction Design program to redesign the W3C specification templates. Their focus was primarily on user research, and went a bit beyond the scope of this project, but they did wrap up the year with a first round of design work and user testing, yielding some recommendations to help guide our efforts through this project and beyond. You can read more about their project on the Jefferson + W3C Collaboration blog.

Audiences

The general audience for any W3C specification is the World Wide Web community at large. This community can be broken down further into various roles:

Specification Developers - spec editors, working group members, reviewers, and other community members who help develop the specifications
Implementers - software engineers who implement the specifications into browsers, for authors to use
Testers - QA engineers and volunteers, who write tests for implementations’ specification compliance
Authors - designers, developers, and educators who use the specified technology to build products, and who use the specification to teach themselves and each other
Overseers - lawyers, W3C management, AC reps, and others who don't care about the details of the specification but are there to manage the process

The design of the W3C specifications should encourage understanding of and involvement with the specifications. It should facilitate

the understanding of every reader--whether a twenty-year veteran of the Web standards process or an author or implementer encountering a W3C specification for the first time--of the purpose, status, and genesis of the specification and its openness to change
the engagement of implementers to give feedback and contribute tests as well as implement and correct their implementations
the engagement of testers in improving the test coverage of the specs and reporting errors and interop failures to the spec editors and implementers
the engagement of authors who are self-taught to play with and learn new technologies, to report problems, create documentation, and potentially get involved in implementation, test suite, or specification development
and the engagement of specification developers in each others’ work, to facilitate the coordination and interaction of the various parts of the Web platform.

Specifications are live documents, and this should be reflected in the template. W3C is an open standards organization, and this, too, should be reflected in the template.