-
Notifications
You must be signed in to change notification settings - Fork 35
How to review a specification
There are multiple levels at which a spec can be reviewed - from simple spelling and grammar, to making sure the algorithms described actually result in multiple software implementations that produce the same results (i.e., result in two or more "interoperable implementations").
When reviewing a spec, the two most important things are:
-
The spec is written for you to understand: if you don't understand something, it's the Editors fault - not yours! It's your right to ask them to clarify the spec until it makes sense to you.
-
The spec needs to be of high quality: this can include making sure that sentences are clear and concise, and mechanical things like spelling and grammar are correct. If something is unclear, or you feel that it would benefit from having an example, then file a bug. Better yet, do a pull request with some proposed fix!
Specs generally make heavy use of jargon (e.g., "a user agent can respond to changes in the browsing environment"). Jargon is mostly unavoidable, but it's crucial that all jargon be linked to a clear and precise definition. If you find jargon in a spec that doesn't make sense or is not linked to a definition, then it's important to file that as a bug.
Another good way to review a spec is to actually try to implement it in something like JavaScript (or even as a thought experiment). Remember that specs are really just recipes like you find in garden variety cookbooks. While implementing, if you get stuck or something is unclear, then its important to file that as a bug.