ircv3
Add a how-to-write-a-spec guide
I'll be writing this up. It'll be something which actually lays out best practices and guidance for writing specs, and a nice companion to the example spec. Going through 'explain things close together rather than in different sections of the document', 'explain things in the simplest way', etc.
Possible language to recommend against:
Non-normative: Where possible, use 'fictitious' 'imaginary', or some other word when discussing examples, as this more easily explains what's meant to regular implementers.
suggestion from jw: "this section is non-normative and uses fictitious examples" as a recommendation.
07:50 LordRyan: I'm [in favor of keeping] non-normative just because it's commonly used language [in various specifications and projects]; even if you don't know English you see it often enough to know what it means.
Definitely would prefer it to "fictitious", but I'm not sure how our (as-is) non-normative section would be "imaginary" rather than it being nonstandardized yet common behavior. "This section is imaginary"?
Possible further recommendations include Sections 2.3 through 2.8 from the Michigan University Technical Writing Guide
Note to self: Provide general guidance at a reasonable, easily-readable level and link to external more complete/in-depth resources for people who want to go further with it.
one thing i have noticed on the SASL 3.1 spec (which may change in the future when i get around to fixing up my PR) is that replies and errors were together in mixed order and this lead me to believe that one of the replies (908) was actually an error, when an error was also sent (904). so i would suggest having distinctly separate section between replies and errors to avoid mixups like these.