SpecProd/Restyle

From W3C Wiki
< SpecProd
Revision as of 22:27, 2 May 2012 by Tantekelik (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Restyle W3C: Towards a More Usable Spec Template

Scope

This effort is about redesigning the boilerplate content, reworking our content formatting, and tying it all together with a new visual style.

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.

Audiences

Two key audiences:

  • Implementers
  • Authors

No consensus on which is more important. Two viewpoints so far:

  • Authors are more important, and specs should be optimized for them even at the expense of implementers.
  • Authors and implementers are equally important, and specs should be optimized for both, not optimized for one at the expense of the other.

It's generally agreed that information that helps authors also helps implementors.

Low priority audiences:

  • Lawyers
  • AC reps

Additional audiences: (need discussion to determine priority)

  • test suite authors

Proposed Audience Priority

  1. authors
  2. web developers
  3. browser implementers
  4. test suite authors
  5. standards representatives / AC reps
  6. lawyers

Reasoning:

  • With the advent of browse by searching and Google, the era of "specs are primarily for browser implementers" is over.
    • All sorts of people will find themselves at W3C specifications just by searching for the respective technologies, and we should therefore take that strongly into account.
  • Prioritize larger audiences over smaller, and take into account subset relationships
    • There are far more web authors (those that write some HTML, maybe some CSS) than web developers (those that write HTML+CSS+JS+etc.)
      • web developers tend to also be web authors, thus anything that benefits web authors will also benefit web developers
    • There are far more web developers than browser implementers.
      • browser implementers tend to also be web developers, thus anything that benefits web developers will also benefit browser implementers
  • Prioritize builders over talkers
    • It's more important that a browser implementer understand and properly implement a specification, as that's what actually impacts interoperability, than it is that a standards representative / AC rep do so in order to debate a standard.

Note that this proposed Audience Priority is very similar to the HTML Design Principles Constituency Priorities:

  1. authors
  2. implementors
  3. specifiers
  4. theoretical purity

Boilerplate

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, and designing that information.

See SpecProd/Restyle/Content.

Design

This part is about the overal 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 being stablized.

Some useful comments:

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 aspec.

See existing documentation of markup conventions: