I think "How confusing is this going to be to the one consuming this" (assuming you're not writing the front end as well) is the more important question to ask
I've found this to be a wonderful way to get into the heads of dev users before you approach them directly.
Writing good tests is a skill and most developers don’t seem to be as skilled in it as they think.
The same concepts power much of Agile too though: XP & Scrum both complement this.