Proposal for a W3C Publications Style Guide
Susan Lesch
W3C Communications Team
3689 Martha St.
San Diego, CA
92117-1814 USA
Voice: +1.858.483.4819
Fax: +1.509.272.7791
Email: lesch@w3.org
Table of Contents
This paper proposes that W3C produce a set of editorial
recommendations for authors and editors to refer to when writing
technical reports, called TRs for short. Their number and complexity is
increasing. At the time of this writing there were 280 listed on the W3C TR index page. Guidelines may help
us to publish consistently high quality specifications. They would
supplement and not replace our mandatory publication rules, which are
specific to publication day.
The guide could include any properties shared by technical reports
that are not addressed in publication rules. We could bring How
to Write a W3C Technical Report and other help files together in
one place. We could add:
- A production checklist based on our experience
- Commonly misspelled words gathered from experience (compiled in Appendix C)
- Formatting for references - MLA, IETF, W3C, or a hybrid
- Markup techniques, for example, how to mark up examples
- Style sheets and palettes
- A pointer to XMLspec,
a DTD originally used for XML-related publications, and a pointer to
its alternatives
- A pointer to the public W3C mailing list spec-prod@w3.org
Possible goals for this Workshop:
- Ask whether people want to extend publication rules to include a
style guide.
- Learn what NIST's publication guide does for NIST.
- Identify other style guides.
Three years ago, Tim Boland of NIST posted a request
for comments to the W3C www-style@w3.org
mailing list. Tim's work covered not only CSS1 but CSS2 as well. Four
days later, Eric Meyer announced a preview of what became the W3C CSS1 Test Suite. The
suite was a joint effort of W3C, NIST, and Case Western University.
The second inkling I had about QA and the Web came when Daniel
Dardailler who wrote an article for the November 1999 Member Newsletter
proposing W3C QA. Daniel had suggested that we might examine technical
reports for complexity and size.
On October 16, 2000, Karl Dubost attended a Communications Team
teleconference. Karl showed how well the QA and Communications Teams
work together.
To date, W3C technical report reviews may be initiated by
eight or more parties. Please excuse any oversights in
this list; there may be more than eight. The Webmaster does the first
review for conformance to our publication rules. In addition, we have
four areas inside W3C that may be reviewing technical reports:
- Web Accessibility Initiative (WAI)
- QA
- Internationalization Working Group
- Communications Team
and three areas outside the Team:
- Invited Working Groups
- Advisory Committee
- The public
There are a number of ways to look at technical report reviews for
the future.
- Judy Brewer has suggested we have "menus" of reviews. For example,
Menu 1 could be spelling, grammar, punctuation, markup and production
scripts. Menu 2 could be appearance and accessibility. Menu 3 could be
internationalization. This way, we could know exactly what each
reviewer did.
- Daniel Dardailler has identified at least three potential levels of
W3C publication review, which I have modified here.
- Mechanical review by the W3C Webmaster. As our
Webmaster does now, he or she would check:
- the document's URI name and version;
- for the Director's okay;
- correct use of the W3C logo;
- the document's status section;
- markup and CSS validity;
- that all links connect;
- conformance to at least Level A of the Web Content Accessibility
Guidelines;
- correct copyright information.
- Editorial review based on conformance to the style
guide, done by a technical editor or by QA. Much as I do now, he or she
would check for:
- spelling, grammar, and editorial style;
- quality of the abstract and introduction;
- presence of examples or a formal primer;
- conformance section and use of the keywords "must," "must not" and
so on;
- layout of the references and acknowledgments sections;
- document size (does it need splitting?).
- Architectural review by technical experts in the
field, by W3C's Web Accessibility Initiative, the Internationalization
Working Group, and perhaps by a Technical Architecture Group (TAG).
These parties would check for:
- requirements, dependencies, and issue resolution per the W3C Process
Document;
- design considerations such as style and content separation,
modularity and simplicity;
- reuse of schemas, metadata, and graphics.
- Open-ended: other perspectives will surely arise.
We have looked at the goal of improving the quality of W3C
publications through a style guide. We also reviewed a brief history of
one editor's work at W3C, the current situation, and a sketch for the
future. I look forward to input from Workshop attendees during the
discussion period, and from other readers of this paper. Thank you.
The following documents address editorial production by standards
bodies. With two exceptions, they are publicly accessible. This was not
created as a definitive list. Additions and corrections are
welcome.
- J. Postel, and J. Reynolds, Instructions to RFC
Authors, RFC 2223, October 1997.
- ISO/IEC Directives, Part 3,
Rules for the structure and drafting of International
Standards, Third edition, 1997.
- NIST
Technical Publishing Guide (NIST staff only)
- J. Daly, and W3C Team, W3C Publication
Rules (W3C Member-only link), April 2000.
- B. Bos, What is a
good standard? An essay on W3C's design principles,
September 2000.
The Webmaster checks for conformance to W3C Publication Rules.
Compiled in December 2000, the following list is what SL tries to
check after publication at Last Call Working Draft, Candidate
Recommendation, and Proposed Recommendation.
Title
- Title should conform to this pseudo-BNF:
Title [(ACRONYM)] ["Level" n] ["Specification"][: Subtitle]
["Module"] [(nth "Edition")] ["Version" Version_Number]
Grammar
- Delete repeated words.
- Check subject-verb agreement.
- Break long sentences.
- Eliminate first person pronouns which are hard to translate.
- Eliminate contractions (e.g., "don't" should read "do not")?
Spelling
- Spell-check using a US English dictionary.
- W3C uses Merriam-Webster's
Collegiate® Dictionary, 10th
Edition, on the Web as the spelling arbiter because it is free, online,
and thus available to every technical report author and editor. If a
word does not appear there, use the American
Heritage® Dictionary, 4th
Edition, free at bartleby.com. Print dictionaries are used as needed
(for example, Random House and Webster's unabridged, Oxford
Concise).
- Because W3C uses en-US, eliminate en-GB spelling (e.g.,
"standardise" should read "standardize" and "behaviour" should read
"behavior").
Case, Combining Words, and Hyphenation
- Capitalize W3C organizations and products to match the W3C Process Document
(e.g., Working Group, Recommendation).
- Make the case, number of words, and hyphenation in terms match the
W3C Style Guide (proposal in development).
Editorial
- Punctuation must be correct. The Chicago Manual of
Style and the Gregg Reference Manual may be of some
help; (no online versions are available).
- Acronyms must be spelled out in their first occurrence.
- Check References (most commonly, for et al.). Do
the entries match?
- With these exceptions (double quote and single quote) use Unicode names for characters
(e.g., line feed is two words, "#" is a number sign not a crosshatch,
and "." is a full stop, dot, or decimal point, not a period).
RFCs
- Examples should adhere to Reserved Top Level DNS
Names, RFC
2606.
- Use of the Key words for use in RFCs to Indicate Requirement
Levels (e.g., "MUST", "MUST NOT", "REQUIRED") should adhere to
and credit RFC
2119, or explain why not.
Appearance
- Check document-specific style sheets for cascading order, color
contrast, idiosyncrasies.
- Check background color of images (so technical reports can be read
with a user style sheet with a dark background).
- Narrow 'pre' text when examples are too wide for a user agent
full-screen at 640x480.
Markup
- Remove extraneous 's.
- Correct obvious markup errors, and check for consistent markup
(e.g., of attributes and elements).
- Match images' size to their markup's 'width' and 'height' (or they
will be distorted).
- 'alt' text should be present and typo-free.
- Reference links (e.g., [URI]) should occur at minimum at the first
mention of the source.
The following table lists the forty or so most commonly confused
terms used in W3C technical reports since November, 1999. In some cases
there are good arguments for usage other than that listed here, and
these differences are yet to be resolved.
Term |
Explanation |
anti-alias |
hyphenate |
ASCII |
all caps |
base64 |
lowercase, one word |
Bézier |
always capitalize, and accent the first é |
braille |
capitalize when talking about Louis Braille |
built-in |
hyphenate when used as an adjective or noun, not when a verb |
dingbat |
one word |
ECMAScript |
one word, cap S |
et al. |
no full stop after "et" |
full stop (.) |
not period; dot or decimal point are good alternates |
heading |
term for H1-H6 (tables and HTTP have headers) |
HTTP/1.0 |
needs slash |
HTTP/1.1 |
needs slash |
Java |
cap J |
JavaScript |
cap S |
Level 1, 2, 3 |
cap L when referring to a W3C technical report |
line feed |
two words |
lowercase |
one word |
markup |
one word, except when a verb |
MIME type |
two words, MIME is all caps |
namespace |
lowercase unless referring to Namespaces in XML |
number sign (#) |
not crosshatch |
on-line |
hyphenate |
PDF |
all caps |
PostScript |
cap S |
read-only |
hyphenate |
ruby |
lowercase |
schema |
lowercase |
semicolon |
one word |
stand-alone |
hyphenate |
style sheet |
two words |
subset |
no hyphen |
superset |
no hyphen |
uppercase |
one word |
URI reference |
usually not URI Reference or URI-Reference |
user agent |
lowercase |
user interface |
lowercase |
Web |
always capitalize |
Web site |
two words, capitalize Web |
well-formed |
hyphenate |
white space |
two words |
worldwide |
one word |
World Wide Web |
three words, no hyphen |
W3C Note |
not W3C NOTE |