In an earlier version of the docs I actually had the spec in the readme but felt the sheer size was enough to send folks running. Using the readme to describe the spec (which I realize needs work!) allowed for a clean separation.