Requirements gathering

Dear all,

I think you may have noticed from the tracker spam that I have  
requirements gathering for APIs on my mind!

I'd like to strike a balance whereby we do gather enough requirements  
to give ourselves a rough idea of the area that each API should cover,  
but without becoming too formal.

Where form is concerned, for each requirement I tend to think that a  
simple, clear sentence should usually suffice (unless there is  
dissent), if possible using an RFC 2119 keyword so that the result can  
be evaluated against it. For example:

   The frobulator MUST expose a way to frobulate.
   The Math API MAY support additions, if we can solve the technical  
issues involved.
   Solving the Halting Problem SHOULD NOT be supported for version 1.

One of my primary goals here is to limit feature creep, and to make it  
possible to release simple APIs fast — and if there's more to do on a  
given API there is nothing keeping us from publishing a v2 or v3  
within the same charter that we have (we are limited in scope but not  
in how many iterations we perform within that scope).

According to that, "MUST" does not mean "we want feature X" but rather  
"if feature X is not included then we think that the API will be  
completely unusable". "SHOULD" means "we really, really want it" as in  
"we'd pay good money for it". "MAY" is for stuff that could get in if  
it's really cheap and obvious, or that would be cool to consider for  
the following version.

Be honest — it shows. And people who've shown to be honest get more  
political sway down the line ;-)

Another important goal is deciding when to publish the first draft of  
a given API (skip to the last sentence if talk of Patent Policy hurts  
your brain). According to the W3C Patent Policy, the First Public  
Working Draft (FPWD) starts an exclusion period during which people  
can exclude patents from being licensed RF for implementations of that  
specification — after the period has run out they are considered to be  
in if they haven't excluded. Then, when the document reaches the Last  
Call maturity level there is a second similar (but shorter) call for  
exclusions, but it only applies to features that were not already  
covered in the first one. To make a long story short: it is better if  
the FPWD of a specification is feature-complete (even if the features  
aren't perfectly defined).

Finally, I think that this will be easier than just comparing inputs,  
which can be a needlessly bruising exercise for a young group. And  
since people have already created APIs in all of the domains that we  
are chartered to address I expect that they have already considered  
requirements — which should make the process quick and hopefully  
painless.

I would like to have rough consensus on this within a couple weeks, so  
if you want your input to matter get writing now!

--
Robin Berjon
   robineko — setting new standards
   http://robineko.com/

Received on Tuesday, 25 August 2009 13:52:36 UTC