I was recently copied on an email from a team with a lot of new contributors to TripleO that was wondering if there was any sort of tips or guidelines for writing specs. My initial reaction was "The spec templates tell you how to write them." Then I realized that if you haven't ever written a spec before you may not know that. So, with that said, here are some of my thoughts on spec writing:
Disclaimer: These are my thoughts and opinions only. This is not endorsed by TripleO or anyone else in the OpenStack community. I'm just writing it in the hopes that it will be helpful.