Re: pilot case?

On 07/05/2013 19:05 , Brian Kardell wrote:
> In the 'larger picture' we might add advice like:  if it is aimed
> toward w3c, 'use respec with unofficial draft and put it here' in the
> layout... I think that would be a great suggestion.

Tobie put up an example of how to kickstart a spec:

     https://github.com/tobie/respec-example
     http://tobie.github.io/respec-example/

(I just filed a pull request that adds a few more useful configuration 
options.)

ReSpec is by no means a requirement, but its selling points are that it 
takes care of as much of the crap involved in writing a specification as 
possible, it's hackable in JS, and it support Markdown which makes it 
easy to transition it with typical open source docs. (In fact I wonder 
if we could move the data-include module earlier in the processing 
pipeline so that you could <div data-include='README.md'></div> and have 
it just work.)

The two main downsides to ReSpec are that the docs are lagging behind 
the features, and that no one likes the way it handles WebIDL. I expect 
to fix both of these things over the summer.

Another option for specs is to use Anolis. It's a Python tool and it 
doesn't generate the painful specification boilerplate for you, but some 
people like it anyway. (You may be getting a sense that I wrote one of 
these two tools. I'll let you guess which.) At any rate I wouldn't use 
anything other than either ReSpec or Anolis, though if your children are 
misbehaving you can tell them about XMLSpec.

For (automatable) tests, the common harness is testharness.js:

     https://github.com/w3c/testharness.js
 
http://darobin.github.io/test-harness-tutorial/docs/using-testharness.html

For tests that can't be automated, you'll want reftests. Doing them the 
way the CSS WG does them might be the best option.

I don't think that you need anything beyond that in terms of 
conventions. If you come to a group with use cases (yeah, you really 
need those), a spec, and tests then you're already doing great.

-- 
Robin Berjon - http://berjon.com/ - @robinberjon

Received on Thursday, 9 May 2013 16:03:32 UTC