W3C home > Mailing lists > Public > www-qa-wg@w3.org > August 2004

[SpecGL Draft] B. GP Write simple direct statements in the scope

From: Lynne Rosenthal <lynne.rosenthal@nist.gov>
Date: Wed, 11 Aug 2004 08:38:23 -0400
Message-Id: <6.0.0.22.2.20040811083728.01c45398@wsxg03.nist.gov>
To: www-qa-wg@w3.org
Good Practice: Write simple, direct statements in the scope.

What does this mean?
When writing the scope, be direct and write simple, understandable 
statements of facts.  Don’t include any requirements in the scope section.

Why care?
This one of the first sections a reader reads, so it is important to 
capture their attention and make sure they understand what the 
specification is about.

Techniques:
Use statements such as: This document
    * specifies a method of …
    * specifies the characteristics of …
    * defines …
    * establishes s system for …
    * establishes general principles for …
    * is a guide for …

Examples:
 From CC/PP 
<http://www.w3.org/TR/2004/REC-CCPP-struct-vocab-20040115/#ScopeOfDocument>http://www.w3.org/TR/2004/REC-CCPP-struct-vocab-20040115/#ScopeOfDocument 
“CC/PP Structure and Vocabularies …defines a client profile data format, 
and a framework for incorporating application- and operating 
environment-specific features.”


--Lynne 
Received on Wednesday, 11 August 2004 12:38:43 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.30 : Thursday, 9 June 2005 12:13:17 GMT