W3C Tech Report editor's materials

Thanks to Antoine, Daniel, and Jon for agreeing to be our first
official Working Group document editors and taking on this
important role.

There are a bunch of conventions that have evolved over time
for our official Technical Reports (the superclass to which
Working Drafts, Candidate Recommendations, Proposed
Recommendations, Recommendations, and Working Group
Notes belong.)  It can look somewhat daunting for first-time
W3C document editors but really, there's lots of help
available.  Also, it's good to use the opportunity presented
by new editors arriving on scene to review and improve upon
the how-to documentation that has grown (and rotted) over
time.  So, please save any notes you may have on what's
not clear or (later, as you know what's expected) what may
have become obsolete in older materials.

Here are some quick pointers (this is from mail I just sent
privately to Antoine, Daniel, and Jon, with some additions
to point 5 and an additional point 6):

1. There is a Manual of Style [1].  Some parts of this manual are
   optional, some parts are mandatory.  The mandatory parts are
   ultimately enforced by a "pubrules checker" tool [2] when we're
   ready to request formal publication.  The most recent version
   of [2] can also produce a template for the type of document
   you say you're writing.  It's worthwhile starting with that template.

   [1] http://www.w3.org/2001/06/manual/
   [2] http://www.w3.org/Guide/pubrules

2. A document is an official W3C Technical Report iff it is published
   in "/TR space" and indexed on the Technical Reports page
   http://www.w3.org/TR/ .  Regardless of what a document may
   claim by styling or by title, if it's not on /TR and in www.w3.org/TR/
   then it's not an official W3C Technical Report.

3. To reduce the confusion about point 2, we strongly discourage
   editors' drafts from calling themselves Working Drafts, from using
   the full Working Draft stylesheet, etc.  The Style for Group-internal
   Drafts [3] talks more about this.  What I personally recommend is
   to take the Working Draft template from pubrules and change the
   stylesheet link back to base.css and change the subtitle to
   "W3C Editor's Draft".

   [3] http://www.w3.org/2005/03/28-editor-style.html

4. There's more information and other pointers on the W3C Editors'
   Home Page [4] that you can read at your leisure :) and in The
   Art of Consensus [5] under "more advice on specification
   development".

   [4] http://www.w3.org/2003/Editors/
   [5] http://www.w3.org/Guide

5. One item that's not identified in [4] is the mechanics of putting
   things on the W3C Web site.  We (i.e. you) are free to put things
   under our Working Group tree [6] in pretty much any manner that's
   convenient.  It's probably worthwhile creating a SKOS/ level under
   this directory.  I recommend document names such as
   SKOS/ucr-yyyymmdd.html for SKOS Use Cases and Requirements.

   [6] http://www.w3.org/2006/07/SWD/

   If you expect that a single "document" will have multiple component
   files (e.g. images, custom stylesheets, RDF or OWL examples)
   then make a directory named SKOS/ucr-yyyymmdd/ and put
   everything related to that document in the (sub) directory.  The
   main file itself should then be named Overview.html (that's the
   name our W3C servers are configured to prefer over, say, index.html)
   We would still cite this document as SKOS/ucr-yyyymmdd (without
   a trailing '/').  And generally we would cite the .html variant without
   including ".html".  Among other things, that makes for a straight-
   forward naming transition from single-file document to multi-file
   document.   The readers do not need to know the mechanics of
   how the document is actually stored in our filesystem!

   When you do make, e.g. SKOS/ucr-20061114.html, let's also
   make a URI for "the latest version of the UCR document".  We'd
   call it simply SKOS/ucr (for example).   It may be easier, in fact,
   to edit a 'live' document in SKOS/ucr and periodically make
   dated (SKOS/ucr-yyyymmdd) snapshots for WG review when you
   collectively feel you have reached a sensible review point.

   There are 3 principal ways to actually put things on www.w3.org.
   These are cited in [5] under the "Edit w3.org using JigEdit, WebDAV,
   or (for experts) CVS".  Read those three links and decide which
   will work most conveniently for you.  Co-editors need not all use
   the same mechanism to update the files but it's best if you do
   use the same editing tools as that will make the actual file
   diffs easier to interpret if and when you need to resort to looking
   at file diffs.

   If you do decide to use CVS then you'll have to ssh-enable your
   environment as well.  All of this is described in the CVS instructions
   linked from [5].

6. It is fine to send HTML attachments to the WG mailing list.  These
   get archived and the archive URI for the attachment is fine to cite
   just as if the document were stored directly in WG space [6].  It is
   sometimes friendlier not to send the attachment to everyone's
   inbox but still post it in mail; do this by sending a message with
   the attachment to www-archive@w3.org.  After posting, go to the
   public archive page [7], find your message, and cite the URI of
   the attachment in a message to the WG mailing list.

   [7] http://lists.w3.org/Archives/Public/www-archive/

-Ralph

Received on Thursday, 9 November 2006 17:14:30 UTC