- Rules are good.
When profiling, set up your conventions, so that you don't have to think about it.
- Explain what you are doing and why.
Description fields explain what you are doing. Requirements fields explain why. Use full sentences.
- Show is better than tell.
You need to have examples, plan for it.
- Don’t do any more than you have to.
When profiling, don't profile stuff you don't care about (and don't profile out stuff just because you don't care. It makes it easier for others to reuse resources they may already have). That may mean using slices to make sure that you have "one like this." That may be hard at first, but your implementers will thank you.
- Make the biggest one do the heavy lifting.
Make the server be the one to implement all the options, and let the clients choose when there is more than one way (e.g., GET/POST, JSON vs. XML), et cetera.
- Don’t expect to be great at it at first.
We're all learning this stuff, even Grahame makes mistakes.