Some draft notes about writing specifications

Just notes, not very well written but ideas that I want to record  
somewhere.
www-qa seems appropriate for it.


* SpecGL:
   QA Spec Guidelines very useful to create a specification. It is  
really a guide not rules. The more we read them, the more we realize  
that they help to ask the right questions.


* Think small: 	
   A WG should not be chartered for too many specifications, only a  
few and small specifications. Small don't link less resources, but  
more resources to achieve the work quickly with a short schedule.


* Break it down:
   If the technology is too big, break it down in small modules. It  
means pushing a set of features to implement that will be  
independent. A kind of  feature/release of software cycle. Easier to  
manage, easier to move forward, easier to maintain on a long term,  
better for small increments.


* Overload:
   WG must not work on many modules at the same time, just a few. An  
editor should not be assigned to many specifications at the same  
time. WGs have limited resources, if they can't achieve the goals, it  
means they have too much work. Ask more resources from the public and  
the members, or cut the work. We can't do everything.


* Test cases:
   For every proposed features right at the start. Specifications are  
for developers first, software engineers need (want) to code (play),  
then they need materials for this. If each time a feature is  
proposed, one or more test cases are given, then the software  
engineers can try to implement, see if there is trouble in the  
specification, see if it's a cool technology. It will help review  
process, it will help the adoption of the technology. It will reduce  
the CR hurdles.


* Testable assertions:
   As an exercise for writing. How can I write this feature so each  
statement is testable?


* Loosely Joined:
   Small specs which define interactions with others specifications  
but not too much constraints or at least constraints keeping a  
logical flexibility. friction here with normative dependencies.  
Example: An HTTP connection can break without breaking the Web.


* Normative references:
   For now, we do not do a very good job to identify dependencies. We  
identify dependencies from a technology to another technology. but  
not that much to a section of a technology or another specific  
requirement.

--------------------------------------------------------------
	Now:     Spec A              --->  Spec B
--------------------------------------------------------------
	Better:  Spec A (section 3)  --->  Spec B (section 5)
	Better:  Spec A (feature z)  --->  Spec B (feature y)
--------------------------------------------------------------

Why? because if a graph of these dependencies was made, it means when  
you update a spec, you would know both directions the influence of  
technologies on other specifications.
If the whole system is becoming to be impossible to modify because  
too much intertwinned dependencies, it means that we are in a too  
rigid mode, and this is the time to break things or that there are  
missing flexible joint (in between technologies).


* Classes of Products:
   We have a tendency to forget about those. Specifically authoring  
tools. Creating content has a lot of implications, which is not only  
create a valid document, but the interaction with other pieces of the  
Web architecture (like for example setting the content type on a  
server and how managing conflicts, errors, ...). We start to see  
things like
	"Authoring tools and markup generators are conformant
	if they only produce conformant documents."
but it's not enough, because it means that we are forgetting that the  
document evolves in a context which is not only the document, but  
there are a server, an architecture, users, etc. The ecology of the  
system.



* In situ Issues:
   When a spec is in development at the start, maybe links to issues  
list where the feature is being discussed, so that reviewers have a  
bit more context of the discussions going on and will avoid to raise  
the same issue.


* Features Consistent layout:
   Some specs are very dry in terms of prose, some are very verbose  
and bury the features in the prose. There must be an effort done on  
the usability of the specification. (Think Tufte - http:// 
www.edwardtufte.com/tufte/ ). There is certainly a middle ground.
    See proposal of Thierry Kormann at QA Workshop.
    http://www.w3.org/2001/01/qa-ws/pp/thierry-kormann-ilog
    http://www.w3.org/2001/01/qa-ws/slides/thierry-kormann-ilog
    http://www.w3.org/2001/01/qa-ws/agenda
    See Björn's email
    http://lists.w3.org/Archives/Public/www-qa/2005Jul/0006


===> There must be a lot of other topics, but things on top of my  
head for the last couple of weeks.


-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Tuesday, 29 August 2006 01:33:49 UTC