A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).

Specs/howto: Difference between revisions

From WHATWG Wiki
Jump to navigation Jump to search
m (HowToWriteASpec moved to How to write a spec: No need for CamelCaps)
m (Formatting)
Line 1: Line 1:
<h1>How to Write a Specification</h1>
author: [mailto:[email protected] Josie Wernecke]
<p>author: [mailto:[email protected] Josie Wernecke]</p>
<p>status:  DRAFT (25 June 2009)</p>
<h2>About This Document</h2>
<p>This document explains basic guidelines for writing a specification and is based on information provided by Ian Hickson, editor of the [http://www.whatwg.org/specs/web-apps/current-work/multipage/ HTML 5 Specification].</p>
<h2>Audience</h2>
<p>This document focuses primarily on specifications aimed at browser implementors. The content of these specifications focuses on API calls that browsers implement and the required browser behavior under all possible cases. Specifications for user interface design and for authored content are not addressed here.</p>
<h2>Organization</h2>
<p>Organize the specification by classes. This is a reference document, not a teaching document, so the order should reflect the class hierarchy, with functional groupings of classes where appropriate.</p>
<h2>Content</h2>
<p>Content in a specification falls into two general categories:  <em>normative</em> and <em>informative</em>. <em>Normative</em> content includes the requirements and definitions and uses verbs such as <em>must</em>, <em>should</em>, and <em>may</em>. If a normative statement uses the verb <em>must</em>, the browser implementor should be able to write a test case for it. (If it is not possible to write a test case for the statement, do not use the word <em>must</em>.) <em>Informative</em> content is everything that is not normative. Informative (non-normative) content includes diagrams and code examples&mdash;very useful content, but supportive in nature to the actual browser requirements.</p>
<h4>IDL Section</h4>
<p>The IDL section (a gray box in the HTML 5 Specification) provides the complete definition of all attributes, methods, and parameters for a given class. Use the IDL format defined in [http://dev.w3.org/2006/webapi/WebIDL/ Web IDL].</p>
<h4>Attributes</h4>
<p>For each attribute, include the following content:</p>
<ul>
<li>Purpose or general use of the attribute. Use the &lt;dfn&gt; tag for the definition.</li>
<li>What the browser must do when it retrieves the attribute ("on getting"). This is normative content.</li>
<li>What the browser must do when it writes a value to the attribute ("on setting"). This is normative content. This content must include requirements for setting the attribute to <em>any</em> value, not just to valid values.  For example, the on setting description for an attribute that requires a float value must also prescribe what the browser does when the value is set to values of infinity, to zero, or to NaN (not a number).</li>
</ul>


<h4>Methods</h4>
status: DRAFT (25 June 2009)
<p>For each method, include the following content:</p>
<ul>
<li>Purpose or general use of the method. Use the &lt;dfn&gt; tag for the definition.</li>
<li>What happens when the method is called. Include a list of numbered steps that describe what happens when the method is invoked. Be sure to cover every case. This list of steps helps the browser implementor ensure that every steps is covered and tested. </li>
</ul>
<p>Use the &lt;var&gt; tag for parameters and &lt;code&gt; tag for method names.</p>


<h2>Language</h2>
== About This Document ==
<p>Refer to the [http://www.ietf.org/rfc/rfc2119.txt RFC2119] for the definitive use of verbs such as <em>must</em>, <em>should</em>, and <em>may</em>. If you use the verb <em>must</em>, the implementor must be able to write a test case for this requirement. The verb <em>may</em> merely grants permission and is used rarely. Do not use "may not."</p>
 
<h2>References</h2>
This document explains basic guidelines for writing a specification and is based on information provided by Ian Hickson, editor of the [http://www.whatwg.org/specs/web-apps/current-work/multipage/ HTML5 Specification].
<p>The following references provide useful information about specification writing and tools to aid the process of writing and producing a specification.</p>
 
<ul>
== Audience ==
<li><b>Language and terminology:</b>  [http://www.ietf.org/rfc/rfc2119.txt RFC2119]. This document explains when and why to use those spec'y verbs like <em>must</em>, <em>may</em>, and <em>should</em>.</li>
 
<li><b>Interface definitions:</b> [http://dev.w3.org/2006/webapi/WebIDL/ Web IDL]. This document defines an interface definition language (IDL) that is useful for describing interfaces intended to be implemented in web browsers. It defines how to write the IDL blocks, how to overload methods, and the basics of common JavaScript bindings. This standard format helps to streamline the definitions for common script objects and allows the spec to focus on defining the unique aspects of the requirements.</li>
This document focuses primarily on specifications aimed at browser implementors. The content of these specifications focuses on API calls that browsers implement and the required browser behavior under all possible cases. Specifications for user interface design and for authored content are not addressed here.
<li><b>Formatting tool: </b>[http://pimpmyspec.net/ Pimp My Spec]. This irreverently named tool defines special markup elements that are processed by a Python script that adds the proper spec numbering, cross references, and table of contents. It's magic! [http://hg.gsnedders.com/anolis/raw-file/tip/example.src.html This page] demonstrates use of the prescribed markup elements.</li>
 
<li><b>Also useful:</b>  [http://www.w3.org/TR/html-design-principles/ HTML Design Principles]. It's always good to keep the Big Picture in mind.</li>
== Organization ==
</ul>
 
Organize the specification by classes. This is a reference document, not a teaching document, so the order should reflect the class hierarchy, with functional groupings of classes where appropriate.
 
== Content ==
 
Content in a specification falls into two general categories: ''normative'' and ''informative''. ''Normative'' content includes the requirements and definitions and uses verbs such as ''must'', ''should'', and ''may''. If a normative statement uses the verb ''must'', the browser implementor should be able to write a test case for it. (If it is not possible to write a test case for the statement, do not use the word ''must''.) ''Informative'' content is everything that is not normative. Informative (non-normative) content includes diagrams and code examples&mdash;very useful content, but supportive in nature to the actual browser requirements.
 
==== IDL Section ====
 
The IDL section (a gray box in the HTML5 Specification) provides the complete definition of all attributes, methods, and parameters for a given class. Use the IDL format defined in [http://dev.w3.org/2006/webapi/WebIDL/ Web IDL].
 
==== Attributes ====
 
For each attribute, include the following content:
 
* Purpose or general use of the attribute. Use the &lt;dfn&gt; tag for the definition.
* What the browser must do when it retrieves the attribute ("on getting"). This is normative content.
* What the browser must do when it writes a value to the attribute ("on setting"). This is normative content. This content must include requirements for setting the attribute to ''any'' value, not just to valid values. For example, the on setting description for an attribute that requires a float value must also prescribe what the browser does when the value is set to values of infinity, to zero, or to NaN (not a number), unless that is already defined in the IDL section.
 
==== Methods ====
 
For each method, include the following content:
 
* Purpose or general use of the method. Use the <code>dfn</code> element for the definition.
* What happens when the method is called. Include a list of numbered steps that describe what happens when the method is invoked. Be sure to cover every case. This list of steps helps the browser implementor ensure that every steps is covered and tested.
 
Use the <code>var</code> element for parameters and <code>code</code> element for method names.
 
== Language ==
 
Refer to the [http://www.ietf.org/rfc/rfc2119.txt RFC2119] for the definitive use of verbs such as ''must'', ''should'', and ''may''. If you use the verb ''must'', the implementor must be able to write a test case for this requirement. The verb ''may'' merely grants permission and is used rarely. Do not use "may not."
 
== References ==
 
The following references provide useful information about specification writing and tools to aid the process of writing and producing a specification.
 
* '''Language and terminology:''' [http://www.ietf.org/rfc/rfc2119.txt RFC2119]. This document explains when and why to use those spec'y verbs like ''must'', ''may'', and ''should''.
* '''Interface definitions:''' [http://dev.w3.org/2006/webapi/WebIDL/ Web IDL]. This document defines an interface definition language (IDL) that is useful for describing interfaces intended to be implemented in web browsers. It defines how to write the IDL blocks, how to overload methods, and the basics of common JavaScript bindings. This standard format helps to streamline the definitions for common script objects and allows the spec to focus on defining the unique aspects of the requirements.
* '''Formatting tool: '''[http://pimpmyspec.net/ Pimp My Spec]. This irreverently named tool defines special markup elements that are processed by a Python script that adds the proper spec numbering, cross references, and table of contents. It's magic! [http://hg.gsnedders.com/anolis/raw-file/tip/example.src.html This page] demonstrates use of the prescribed markup elements.
* '''Also useful:''' [http://www.w3.org/TR/html-design-principles/ HTML Design Principles]. It's always good to keep the Big Picture in mind.

Revision as of 10:15, 18 October 2009

author: Josie Wernecke

status: DRAFT (25 June 2009)

About This Document

This document explains basic guidelines for writing a specification and is based on information provided by Ian Hickson, editor of the HTML5 Specification.

Audience

This document focuses primarily on specifications aimed at browser implementors. The content of these specifications focuses on API calls that browsers implement and the required browser behavior under all possible cases. Specifications for user interface design and for authored content are not addressed here.

Organization

Organize the specification by classes. This is a reference document, not a teaching document, so the order should reflect the class hierarchy, with functional groupings of classes where appropriate.

Content

Content in a specification falls into two general categories: normative and informative. Normative content includes the requirements and definitions and uses verbs such as must, should, and may. If a normative statement uses the verb must, the browser implementor should be able to write a test case for it. (If it is not possible to write a test case for the statement, do not use the word must.) Informative content is everything that is not normative. Informative (non-normative) content includes diagrams and code examples—very useful content, but supportive in nature to the actual browser requirements.

IDL Section

The IDL section (a gray box in the HTML5 Specification) provides the complete definition of all attributes, methods, and parameters for a given class. Use the IDL format defined in Web IDL.

Attributes

For each attribute, include the following content:

  • Purpose or general use of the attribute. Use the <dfn> tag for the definition.
  • What the browser must do when it retrieves the attribute ("on getting"). This is normative content.
  • What the browser must do when it writes a value to the attribute ("on setting"). This is normative content. This content must include requirements for setting the attribute to any value, not just to valid values. For example, the on setting description for an attribute that requires a float value must also prescribe what the browser does when the value is set to values of infinity, to zero, or to NaN (not a number), unless that is already defined in the IDL section.

Methods

For each method, include the following content:

  • Purpose or general use of the method. Use the dfn element for the definition.
  • What happens when the method is called. Include a list of numbered steps that describe what happens when the method is invoked. Be sure to cover every case. This list of steps helps the browser implementor ensure that every steps is covered and tested.

Use the var element for parameters and code element for method names.

Language

Refer to the RFC2119 for the definitive use of verbs such as must, should, and may. If you use the verb must, the implementor must be able to write a test case for this requirement. The verb may merely grants permission and is used rarely. Do not use "may not."

References

The following references provide useful information about specification writing and tools to aid the process of writing and producing a specification.

  • Language and terminology: RFC2119. This document explains when and why to use those spec'y verbs like must, may, and should.
  • Interface definitions: Web IDL. This document defines an interface definition language (IDL) that is useful for describing interfaces intended to be implemented in web browsers. It defines how to write the IDL blocks, how to overload methods, and the basics of common JavaScript bindings. This standard format helps to streamline the definitions for common script objects and allows the spec to focus on defining the unique aspects of the requirements.
  • Formatting tool: Pimp My Spec. This irreverently named tool defines special markup elements that are processed by a Python script that adds the proper spec numbering, cross references, and table of contents. It's magic! This page demonstrates use of the prescribed markup elements.
  • Also useful: HTML Design Principles. It's always good to keep the Big Picture in mind.
Retrieved from "https://wiki.whatwg.org/index.php?title=Specs/howto&oldid=4185"