Specs/style: Difference between revisions

Revision as of 16:12, 6 November 2013

When writing a spec, it is suggested that you adhere to the following guidelines.

Unless otherwise stated, use standard American English spelling.: 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 9: / Line 9: @@
 ; 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.
 == Terminology ==