Position Paper: Workshop on Quality Assurance at W3C
3-4 April 2001

Table of Contents

• Abstract
• Contents of a Style Guide
• Goals for This Workshop
• History
• Current Reviewers
• Future Reviewers
• Conclusion
• Appendix A - Notable Style Guides
• Appendix B - What Is Checked Now
• Appendix C - Commonly Confused Terms

Abstract

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.

Contents of a Style Guide

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

Goals for This Workshop

Possible goals for this Workshop:

1. Ask whether people want to extend publication rules to include a style guide.
2. Learn what NIST's publication guide does for NIST.
3. Identify other style guides.

History

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.

Current Reviewers

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

Future Reviewers

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.
  1. 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.
  2. 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?).
  3. 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.

Conclusion

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.

Appendix A - Notable Style Guides

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.

Appendix B - What Is Checked Now

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.

Appendix C - Commonly Confused Terms

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.