- From: Robin Berjon <robin@w3.org>
- Date: Wed, 08 May 2013 16:04:34 +0200
- To: Brian Kardell <bkardell@gmail.com>
- CC: François REMY <francois.remy.dev@outlook.com>, "public-nextweb@w3.org" <public-nextweb@w3.org>, Alex Russell <slightlyoff@google.com>
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