search

ircv3 / ircv3-specifications

IRCv3 specifications | Roadmap: https://git.io/IRCv3-Roadmap | Code of conduct: http://ircv3.net/conduct.html
http://ircv3.net/
778 stars 79 forks source link

Add a how-to-write-a-spec guide #372

Open DanielOaks opened 5 years ago

DanielOaks commented 5 years ago

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.

RyanSquared commented 5 years ago

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"?

justjanne commented 5 years ago

Possible further recommendations include Sections 2.3 through 2.8 from the Michigan University Technical Writing Guide

DanielOaks commented 5 years ago

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.

RyanSquared commented 4 years ago

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.