Specs/style: Difference between revisions

Revision as of 16:14, 6 November 2013

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. See 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 noun and "dialog" for 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.

Be careful of your use of the terms "file" and "resource".: Make sure your definitions refer only to bags of bits, and not also stuff in the Real World™ (like baskets of apples).

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.

@@ Line 3: / Line 3: @@
 == Spelling ==
-; Unless otherwise stated, use standard American English spelling.
+; 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. See [[wikipedia:Wikipedia:Manual of Style/Spelling|Wikipedia's Manual of Style for spelling]] for assistance.
 ; Use "acknowledgements" instead of "acknowledgments".