W3C home > Mailing lists > Public > www-archive@w3.org > November 2009

Re: Proposed W3C Spec Conventions

From: Doug Schepers <schepers@w3.org>
Date: Thu, 26 Nov 2009 18:47:42 -0500
Message-ID: <4B0F139E.8040007@w3.org>
To: www-archive <www-archive@w3.org>, "Gregory J. Rosmaita" <oedipus@hicom.net>, Janina Sajka <janina@a11y.org>
Hi, Gregory-

You expressed interest and provided feedback on Karl's typographic 
conventions for specifications several months ago.  We have picked up 
that effort again, and I've tried to integrate all the feedback gathered 
at that time.

In response to your comments, I've made the following changes:

* semantic tags such as <em>, <strong>, <dfn>, <var>, <code>, etc. 
wherever possible, rather than <span> or <div>
* named colors rather than numerical color codes
* prefaced notes, issues, and other categories with prose labels in the 
document, rather than relying on text inserted by CSS; CSS insertions 
are now used only for emphasis symbols

If you would review the most recent draft of the documentation [1] and 
the stylesheet [2] for accessibility concerns, I would appreciate it.

[1] http://www.w3.org/People/Schepers/spec-conventions.html
[2] http://www.w3.org/StyleSheets/TR/w3c-tr.css

-Doug Schepers
W3C Team Contact, SVG and WebApps WGs

Doug Schepers wrote (on 11/23/09 3:44 AM):
> Hi, Folks-
> (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.
> I plan on using this (or whatever variant we all decide on) in the specs
> I'm editing (some SVG specs, DOM3 Events). I encourage others to do the
> same, and report back what works, what doesn't work, what's missing, etc.
> (Oh, and I'd really like to see this working with Robin Berjon's ReSpec.js:
> http://dev.w3.org/2009/dap/ReSpec.js/documentation.html )
> Thanks!
> -Doug Schepers
> W3C Team Contact, SVG and WebApps \o/ WGs
Received on Thursday, 26 November 2009 23:47:52 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 7 January 2015 14:43:36 UTC