When writing a spec, it is suggested that you adhere to the following guidelines.
- Use standard American English spelling, unless otherwise stated below.
- Continue the history of the Web and use 'en-US' spelling for your specs and the technologies they document. Consult Wikipedia's Manual of Style for spelling for assistance.
- Use "acknowledgements" instead of "acknowledgments".
- Whenever 'dg' represents the "soft" /d͡ʒ/ sound, it should be followed by an 'e' or an 'i', to ensure it is not confused with the "hard" /dɡ/ sounds.
- Use "dialogue" for the definitive noun (the conversation) and "dialog" for the adjectival noun (the box on the screen) and all other parts of speech.
- Whenever a word has a '-log(ue)' dichotomy, only keep '-ue' for the definitive noun: "monologue", "dialog box", "catalogging", "homologous".
- Use "cannot" when something is impossible or prohibited.
- "Can not" implies a choice; "cannot" prevents one.
- Use double quotation marks for outer quotes and single quotation marks for inner quotes.
- This is slowly becoming the worldwide standard anyway, but just in case you need to be reminded.
- Where applicable, use double quotation marks for quoted terms or scare quotes and single quotation marks for literal sequences of characters.
- You could use double quotation marks for the latter, but single ones are less bulky. Besides, it's better to use semantic markup and/or styling to get the message across anyway.
- Only include between quotation marks what is actually being quoted.
- It's OK to have punctuation on the outside of a quotation mark. It's even OK to have punctuation on both sides of a quotation mark, if that's how things turn out.
- Avoid parenthesizing an entire sentence within another sentence.
- It's OK to let a parenthetical sentence stand on its own.
- Include trailing punctuation within parentheses.
- You should be able to remove a parenthetical without breaking anything around it; if you have trailing punctuation outside parentheses, removing the parenthetical will leave the punctuation orphaned.
Bags of bits
- Be careful of your use of the terms "file" and "resource".
- Make sure your definitions refer only to bags of bits, and not also to stuff in the Real World™ (like baskets of apples).
Collections of values
|and||uniqueness doesn't matter||uniqueness matters|
|order doesn't matter||"unordered list"||"set"|
|order matters||"list"||"ordered set"|
|and||only one key per value||more than one key per value|
|only one value per key||"bidirectional map"||"map"|
|more than one value per key||"inverse map"||"multimap"|
- Use "object" for a map whose values can be functions.
- This helps to distinguish cases where values might not be static data types.
- Do not use "dictionary" for any collection of values.
- There is potential for confusion between a map (which, as mentioned above, can have only one value per key) and a Real World™ dictionary (which can have more than one definition per headword).
Willful violations of other specs
- When willfully and deliberately violating standards set out in other documents, use the term "willful violation" instead of simply "violation".
- "Violation" makes you sound naughty; "willful violation" makes you sound knowledgeable.