index.html
12.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>W3C Editors' Home Page</title>
<link rel="stylesheet" href="/StyleSheets/generic-base-1.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="/Guide/guide2006.css" />
<link rel="shortcut icon" href="/Icons/WWW/Literature.gif" />
<link rel="shortcut icon" href="../../Icons/WWW/Literature.gif" />
<link rel="start" title="Guidebook for W3C Collaborators" href="../../Guide/" />
<link rel="bookmark" title="Pubrules" href="../../Guide/pubrules" />
<link rel="bookmark" title="W3C Manual of Style" href="../../2001/06/manual/" />
<link rel="copyright" title="Copyright" href="../../Consortium/Legal/ipr-notice#Copyright" />
<link rel="help" title="Finding your way at W3C" href="../../2002/03/new-to-w3c" />
<link rel="glossary" title="Index of W3C terms" href="../../Help/siteindex" />
<style type="text/css">
/*<![CDATA[*/
#Logo { text-align:left;}
/*]]>*/
</style>
</head>
<body>
<div id="header">
<span class="logo">
<a href="/">
<img src="/Icons/WWW/w3c_home_nb" alt="W3C" height="48" width="72" />
</a>
</span>
<div class="breadcrumb"><a href="/Member/">Member</a> → <a href="/Guide/">The Art of Consensus</a> →
<h1>W3C Editors' Home Page</h1></div>
<p class="baseline">This <strong>Guidebook</strong> is the collected wisdom of the W3C Group Chairs and other collaborators.</p>
</div>
<div class="toc">
<h4>Also On This Page → </h4>
<ul>
<li><a href="#intro">Introduction</a> • </li>
<li><a href="#start">Getting started</a> • </li>
<li><a href="#quality">Guidelines</a> • </li>
<li><a href="#grammars">Grammars</a> • </li>
<li><a href="#authoring">Authoring Tools</a> • </li>
<li>
<a href="#tools">Tools</a>
</li>
</ul>
</div>
<div class="toolbox box">
<h4>Nearby</h4>
<ul>
<li>
<a href="../../Guide/pubrules">Pubrules</a>
</li>
<li>
<a href="../../2001/06/manual/">Manual of Style</a>
</li>
<li>
<a href="http://lists.w3.org/Archives/Public/spec-prod/">spec-prod mailing list</a>
</li>
</ul>
</div>
<div id="Content">
<h2>
<a name="intro" id="intro">Introduction</a>
</h2>
<p>One of the main accomplishments at W3C is to write specifications and create standards out of them. While the Working Groups at large are responsible for building consensus on the technical decisions, the editors have the heavy responsibility of transforming these decisions into actual specifications.</p>
<p>This page tries to gather resources that can help editors do their job: documentation, tools, tutorials, etc. If you know other resources that would benefit editors by being listed here, please inform the W3C Communication Team at <a href="mailto:w3t-comm@w3.org">w3t-comm@w3.org</a>.</p>
<h2>
<a name="start" id="start">Where to start?</a>
</h2>
<p>If you are a newly appointed editor in your Working Group, here is some advice that should be useful to get you started.</p>
<ul>
<li>Get an <a href="http://lists.w3.org/Archives/Member/chairs/1999JanMar/0056">idea of the role of an editor</a> at W3C</li>
<li>Read the <a href="../../Guide/pubrules">W3C Publication Rules</a> (often referred as <q><dfn>pubrules</dfn></q>) and ask advice on the points that are unclear; if your document doesn't comply with these rules, it cannot be published as a W3C technical report.</li>
<li><a href="../../Guide/transitions">How to Organize a Recommendation Track Transition</a> explains the process to get a document published as a technical report.</li>
<li>The <a href="../../Guide/pubrules">Pubrules Checker</a> is a tool that can help you assess whether or not your document complies with pubrules.</li>
<li>Review <a href="/TR/WCAG20/">WCAG 2.0</a></li>
<li>All W3C editors are invited to join the <a href="http://lists.w3.org/Archives/Public/spec-prod/">publicly archived mailing list <spec-prod@w3.org></a> to share and discuss the techniques and tools used to produce W3C specifications.</li>
<li>if you're using JigEdit to edit documents, the <a href="/Guide/Jigedit">JigEdit Guide</a> is a useful resource</li>
</ul>
<h2>
<a name="quality" id="quality">Guidelines on W3C specifications editing</a>
</h2>
<p>W3C has developed a set of resources giving advices and guidelines on editing W3C specifications in varous domains:</p>
<ul>
<li>The <a href="../../2001/06/manual/">W3C Manual of Style</a> is a collection of rules you're invited to follow to make your document clearer and adapted to the common style at W3C.</li>
<li>Begun in 1992 and only a little out of date, the <a href="../../Provider/Style/">Style Guide for online hypertext</a> by Tim Berners-Lee is a good start on writing for the Web; see also Jakob Nielsen's <a href="http://www.useit.com/alertbox/9710a.html">How Users Read on the Web</a></li>
<li>The <a href="../../TR/qaframe-spec/">QA Framework: Specification Guidelines</a> from the W3C Quality Assurance Activity are a work in progress that became a Candidate Recommendation in November 2003.</li>
<li>The Team has guidelines for a <a href="/2005/03/28-editor-style.html">style for group-internal drafts</a> to avoid confusion with documents published on the <a href="/TR">TR page</a>. Please also review the related <a href="/2004/02/Process-20040205/groups#three-month-rule">Working Group Heartbeat Requirement</a> of the W3C Process.</li>
</ul>
<p><a href="http://www.w3.org/People/Bos/DesignGuide/introduction">Bert Bos's essay on W3C's design principles</a> and <a href="http://www.w3.org/1999/09/specification">Tim Berners-Lee's essentials of a specification</a> may also be a useful reading.</p>
<p>During the internal development of a specification, make sure to distinguish official drafts from internal ones using the <a href="http://www.w3.org/2005/03/28-editor-style.html">style for Group-internal Drafts</a>.</p>
<h2>
<a name="grammars" id="grammars">Grammars</a>
</h2>
<p>W3C editors have developed several types of HTML and XML based grammars to make it easier to develop and maintain their specifications. We try to maintain a <a href="http://www.w3.org/2001/03/09-XML-document-production-tools">list of these grammars</a>; <a href="../../2002/xmlspec/">XMLSpec</a> is the most-often used incarnation of these grammars – Karl <karl@w3.org> plans to work on setting up a documentation for it, but you can see what e.g. <a href="http://www.w3.org/TR/2005/WD-ws-addr-core-20050331/ws-addr-core.xml"><cite>Web Services Addressing 1.0 - Core</cite> looks like in XMLSpec</a> and read a few introductory materials: <a href="http://people.w3.org/rishida/misc/xmlspec-guide.html">Richard Ishida's guide</a>, the <a href="http://lists.w3.org/Archives/Member/w3c-di-wg/2003Jun/att-0156/WritingDIWGDocs.html">DI Working Group introduction to it</a> (Member-only), <a href="http://www.w3.org/2005/07/WhyXMLSpec.html">Why Use XMLSpec?</a> (Member-only).</p>
<p>Some <a href="http://www.w3.org/QA/Group/2002/09/results-survey">raw results of a survey</a> [Member-only] done among editors at the end of 2002 can help you in your choices.</p>
<h2>
<a name="authoring" id="authoring">Authoring tools</a>
</h2>
<p><a href="http://dev.w3.org/2009/dap/ReSpec.js/documentation.html">ReSpec</a> by Robin Berjon.</p>
<p>To create XHTML documents, using <a href="/Amaya">Amaya</a> - W3C Browser/Editor - is a good option to create valid markup, but there are other tools available.</p>
<p>When using XMLSpec, having a good XML editor can help; the following tools have proven useful for some editors:</p>
<ul>
<li><a href="http://www.thaiopensource.com/nxml-mode/">nXML-mode</a> in emacs</li>
<li>XMLSpy for which <a href="http://lists.w3.org/Archives/Member/w3c-html-wg/2007JulSep/0000.html">Altova offers a license to W3C Working Group participants that need it</a> (Member-only)</li>
<li>oXygen XML, for which Syncro Soft offers a license to W3C Working Group participants that need it (<a href="http://lists.w3.org/Archives/Member/w3c-xml-schema-wg/2005May/0016">May 2005 license - Member-only</a>)</li>
<li>XMetal (see Richard Ishida's <a href="http://people.w3.org/rishida/articles/xmetal-setup.html">setup for editing XHTML with XMetal</a>)</li>
<!--
XMetal isn't owned by SoftQuad anymore, apparently
<li>XMetal has also been <a href="http://lists.w3.org/Archives/Member/w3c-ws-arch/2002Feb/0055">made available to W3C Editors</a> (Member-only) thanks to SoftQuad </li> -->
</ul>
<h2>
<a name="tools" id="tools">Tools</a>
</h2>
<p>Here are tools that can prove to be useful when developing your specification.</p>
<ul>
<li>The <a href="http://www.w3.org/Guide/pubrules">Pubrules Checker</a> provides a convenient interface to check the conformance of a document to pubrules.</li>
<li>The <a href="http://www.w3.org/2000/06/webdata/xslt?xslfile=http%3A%2F%2Fwww.w3.org%2F2005%2F06%2Ftr-shopping.xsl&xmlfile=http%3A%2F%2Fwww.w3.org%2F2002%2F01%2Ftr-automation%2Ftr.rdf">Technical Reports shopping list</a> and the <a href="http://www.w3.org/2002/01/tr-automation/tr-biblio-ui">Bibliography Extractor</a> help building bibliographies based on other W3C Technical Reports; there is a <a href="http://lists.w3.org/Archives/Public/spec-prod/2003OctDec/0002.html">similar mechansim</a> for XMLSpec</li>
<li>The <a href="/2004/07/references-checker-ui">TR references checker</a> may help maintain your references list up to date. See also the <a href="/2007/05/ietf-references-checker">IETF references checker</a>.</li>
<li>The <a href="/2003/glossary/">W3C Glossary</a> is a repository of all the terms defined in W3C specifications (and more); a good source to find which terms have already been defined and where</li>
<li>The <a href="http://www.w3.org/2002/01/spellchecker">on-line Spell Checker</a> helps spot misspellings and typos; the <a href="/2002/08/diction">W3C on-line Stylistic Checker</a> helps find the most usual errors identified by the <a href="/2001/06/manual/">W3C Manual of Style</a></li>
<li><a href="http://esw.w3.org/topic/HtmlDiff">different tools</a> are available to produce a <code>diff</code> between 2 HTML versions of a document; W3C offers an <a href="http://www.w3.org/2007/10/htmldiff">on-line HTMLDiff service</a></li>
<li>The <a href="http://validator.w3.org/">MarkUp Validator</a> can help you assess whether your documents are valid HTML, MathML or SVG.</li>
<li>The <a href="http://jigsaw.w3.org/css-validator/">CSS Validator</a> tells you if your use of CSS is correct.</li>
<li>The <a href="http://validator.w3.org/checklink">Link Checker</a> catches all the broken links that may have popped up in your document.</li>
<li>The <a href="http://www.w3.org/2003/09/nschecker">Namespace checker</a> finds potential namespaces URIs in the documents, and makes a few checks on them</li>
<li><a href="http://tidy.sourceforge.net/">HTML Tidy</a>, originally by Dave Raggett and now maintained at SourceForge.net, is a lint that cleans up but does not validate HTML and XHTML. With indent off, Tidy can sometimes shave 10% or more off file size.</li>
</ul>
<p>Most of these tools can be quickly accessed using the <a href="./,tools">so called <code>,tools</code></a> interface: appending <code>,<var>keyword</var></code> to a www.w3.org URI triggers a certain tool on this URI; for instance, appending <a href=",validate"><code>,validate</code></a> to this page's URI will send it to the HTML validator.</p>
</div>
<hr />
<address><a href="/People/Dom/">Dominique Hazaël-Massieux</a> for the Communication Team - Send comments and suggestions to <a href="mailto:w3t-comm@w3.org">w3t-comm@w3.org</a></address>
</body>
</html>