Specs/style - Revision history

GPHemsley: /* Terminology */ Equality

2015-02-25T01:36:32Z

Terminology: Equality

@@ Line 79: / Line 79: @@
 ; When willfully and deliberately violating standards set out in other documents, carefully document the differences from the standards in question, as well as the rationale for each decision to differ.
 : If you don't explain your decision making, there will be no incentive to follow your standard over the existing one.
 [[Category:Spec coordination|*]]

GPHemsley: /* Bags of bits */ "of" -> "with"

2013-11-06T22:53:11Z

Bags of bits: "of" -> "with"

← Older revision		Revision as of 22:53, 6 November 2013
Line 31:		Line 31:
	=== Bags of bits ===		=== Bags of bits ===

	; Be careful of your use of the terms "file" and "resource".		; Be careful with 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).		: Make sure your definitions refer only to bags of bits, and not also to stuff in the Real World™ (like baskets of apples).

GPHemsley: Improve preamble.

2013-11-06T22:52:15Z

Improve preamble.

← Older revision		Revision as of 22:52, 6 November 2013
Line 1:		Line 1:
	~~When writing a spec~~, it is suggested that ~~you~~ adhere to the ~~following~~ guidelines.		To be effective, specs must be written clearly and consistently, using precise and succinct language.

			To facilitate those goals, it is suggested that spec editors adhere to the style guidelines set forth in this document.

	== Spelling ==		== Spelling ==

GPHemsley: /* Willful violations of other specs */ +s

2013-11-06T22:44:23Z

Willful violations of other specs: +s

← Older revision		Revision as of 22:44, 6 November 2013
Line 75:		Line 75:
	; When willfully and deliberately violating standards set out in other documents, use the term "willful violation" instead of simply "violation".		; 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.		: "Violation" makes you sound naughty; "willful violation" makes you sound knowledgeable.
	; When willfully and deliberately violating standards set out in other documents, carefully document the differences from the ~~standard~~ in question, as well as the rationale for each decision to differ.		; When willfully and deliberately violating standards set out in other documents, carefully document the differences from the standards in question, as well as the rationale for each decision to differ.
	: If you don't explain your decision making, there will be no incentive to follow your standard over the existing one.		: If you don't explain your decision making, there will be no incentive to follow your standard over the existing one.

	[[Category:Spec coordination\|*]]		[[Category:Spec coordination\|*]]

GPHemsley: /* Willful violations of other specs */ Add guideline about explicitly documenting willful violations.

2013-11-06T22:43:50Z

Willful violations of other specs: Add guideline about explicitly documenting willful violations.

← Older revision		Revision as of 22:43, 6 November 2013
Line 75:		Line 75:
	; When willfully and deliberately violating standards set out in other documents, use the term "willful violation" instead of simply "violation".		; 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.		: "Violation" makes you sound naughty; "willful violation" makes you sound knowledgeable.
			; When willfully and deliberately violating standards set out in other documents, carefully document the differences from the standard in question, as well as the rationale for each decision to differ.
			: If you don't explain your decision making, there will be no incentive to follow your standard over the existing one.

	[[Category:Spec coordination\|*]]		[[Category:Spec coordination\|*]]

GPHemsley: /* Punctuation */ Add the Oxford comma.

2013-11-06T22:35:03Z

Punctuation: Add the Oxford comma.

← Older revision		Revision as of 22:35, 6 November 2013
Line 12:		Line 12:
	== Punctuation ==		== Punctuation ==

			; Use the Oxford comma.
			: When conjoining three or more items, place a comma between the second-to-last item and the conjunction.
	; Use double quotation marks for outer quotes and single quotation marks for inner quotes.		; 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.		: This is slowly becoming the worldwide standard anyway, but just in case you need to be reminded.

GPHemsley: /* Collections of values */ Try to reduce confusion around the "and".

2013-11-06T21:10:15Z

Collections of values: Try to reduce confusion around the "and".

← Older revision		Revision as of 21:10, 6 November 2013
Line 32:		Line 32:
	=== Collections of values ===		=== Collections of values ===

	{\| class="wikitable" style="min-width: ~~40em~~;"		{\| class="wikitable" style="min-width: 50em;"
	\|+ For a keyless collection of values, use the ~~following~~ term ~~when…~~		\|+ For a keyless collection of values, use the provided term when … and …
	\|-		\|-
	! ~~and~~		!
	! uniqueness doesn't matter		! uniqueness doesn't matter
	! uniqueness matters		! uniqueness matters
Line 48:		Line 48:
	\|}		\|}

	{\| class="wikitable" style="min-width: ~~40em~~;"		{\| class="wikitable" style="min-width: 50em;"
	\|+ For a keyed collection of values, use the ~~following~~ term when there can ~~be…~~		\|+ For a keyed collection of values, use the provided term when there can be … and …
	\|-		\|-
	! ~~and~~		!
	! only one key per value		! only one key per value
	! more than one key per value		! more than one key per value

GPHemsley: /* Spelling */ Remove the "-log(ue)" rule because it's causing too much confusion and raising too many exceptions.

2013-11-06T21:07:06Z

Spelling: Remove the "-log(ue)" rule because it's causing too much confusion and raising too many exceptions.

← Older revision		Revision as of 21:07, 6 November 2013
Line 7:		Line 7:
	; Use "acknowledgements" instead of "acknowledgments".		; 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.		: 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.		; Use "cannot" when something is impossible or prohibited.
	: "Can not" implies a choice; "cannot" prevents one.		: "Can not" implies a choice; "cannot" prevents one.

GPHemsley: /* Spelling */ Try to clarify the distinction between "dialogue" and "dialog" for the purposes of the guideline.

2013-11-06T21:00:45Z

Spelling: Try to clarify the distinction between "dialogue" and "dialog" for the purposes of the guideline.

← Older revision		Revision as of 21:00, 6 November 2013
Line 7:		Line 7:
	; Use "acknowledgements" instead of "acknowledgments".		; 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.		: 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.		; 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".		: 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.		; Use "cannot" when something is impossible or prohibited.

GPHemsley: /* Collections of values */ Do not use "dictionary" for any collection of values.

2013-11-06T20:31:20Z

Collections of values: Do not use "dictionary" for any collection of values.

← Older revision		Revision as of 20:31, 6 November 2013
Line 68:		Line 68:
	; Use "object" for a map whose values can be functions.		; Use "object" for a map whose values can be functions.
	: This helps to distinguish cases where values might not be static data types.		: 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 ===		=== Willful violations of other specs ===