Re: Proposed W3C Spec Conventions

On Monday 2009-11-23 03:44 -0500, Doug Schepers wrote:
> (Forwarding and summarizing from Member-only space.)
> I'm not the first one to suggest this (apparently Karl tried to push
> this earlier this year), but I really think it's time we establish
> some standardized style conventions for W3C specs.
> I took a couple hours to pull together a proposal (attached) based
> on Karl's original along with feedback to that proposal, and
> conventions that I'm familiar with from the SVG and DOM3 Events
> specs; I'm not married to any of it, but any counter-proposals
> should probably stick with at least the level of granularity laid
> out here.
> Please see the attached, and send in counter-proposals or thoughts
> for consideration.

One thing I'm not a big fan of in this proposal is the color
conventions used for "Issue" and "Proposal" text, which swap in a
different foreground color.  I somewhat prefer the styles I've used
a few times, e.g., in ,
which are clearly distinct, but which I find not quite as jarring.

One other note is that I find the styles here:
  # The defining instance of a term is marked up like this: term.
  # Uses of that term are marked up like this.
a bit odd, both because:
 (1) it seems odd to switch to a monospace font for something that's
     not code, and
 (2) defining instances of terms are traditionally styled in
     italics, I think.
I would suggest styling the defining instance in italics and the
uses as the default link styles.


L. David Baron                       
Mozilla Corporation             

Received on Wednesday, 2 December 2009 22:02:40 UTC