I spent some time this afternoon trying out apiary.io – Thanks for the tip @marcwes – really a great piece of software! I built my first relayr draft API in a couple of hours and achieved a higher quality than i would ever expect to at this stage.
Yaray took a quick look at the test code and felt it would be useful. I’m interested to see what the usage stats teach us as we progress the development.
It’s not quite Documentation Driven Design, but the preview mode gives such fast feedback on how the API looks to a newcomer, that you can’t help but add a little explanation. This is a very good thing… As well as defining what others see, writing extensively, allows you to think through your problems in much greater depth than you would otherwise. When you only have a small team, that is golden!
I’ve not shaken my inherent distrust of significant whitespace, but today it didn’t seem to matter. I took maybe three hours and sketched out a v0.1 API. It’s still rough and will evolve over the next couple of days. I’ll share here, but know there is a lot to do.
watch this space!