There is a discussion on documentation in one of the issues[1]. Feel free to weigh in!

[1] https://github.com/18F/api-standards/issues/19