minimal-vocabulary - Revision history

Aaronpk: Replace with {{DISPLAYTITLE:}}

2020-07-18T16:30:47Z

Replace <entry-title> with {{DISPLAYTITLE:}}

← Older revision		Revision as of 16:30, 18 July 2020
Line 1:		Line 1:
	~~<entry-title>~~minimal vocabulary~~</entry-title>~~		{{DISPLAYTITLE:minimal vocabulary}}
	One aspect of the [[start-simple]] [[microformats]] [[principle]], and one of several [[naming-principles]].		One aspect of the [[start-simple]] [[microformats]] [[principle]], and one of several [[naming-principles]].

Tantek: /* benefits */ add note about lower cognitive load, and applies to authors as well as developers

2009-07-06T20:25:00Z

benefits: add note about lower cognitive load, and applies to authors as well as developers

← Older revision		Revision as of 20:25, 6 July 2009
Line 5:		Line 5:

	== benefits ==		== benefits ==
	Minimizing the vocabulary used for properties (and values) of a microformat helps make and keep microformats easier to understand.		Minimizing the vocabulary used for properties (and values) of a microformat helps make and keep microformats easier to understand.

			Fewer terms in a vocabulary means a lower cognitive load for anyone seeking to understand that vocabulary, whether they are authors of markup, or developers of tools that parse markup, or developers of tools that take abstract representation of data in such vocabularies (e.g. in JSON) and write code to process them.

	Minimizing the introduction of ''new'' vocabulary is particularly important. Doing so:		Minimizing the introduction of ''new'' vocabulary is particularly important. Doing so:
	* Keeps microformats as a whole easier to understand (the smaller the total vocabulary of all microformats).		* Keeps microformats ''as a whole'' easier to understand (the smaller the total vocabulary of all microformats).
	* Reduces confusion with the re-use of existing technologies.		* Reduces confusion with the re-use of existing technologies.

Tantek: /* renaming example organization name */ clearer styling

2009-06-12T06:26:44Z

renaming example organization name: clearer styling

← Older revision		Revision as of 06:26, 12 June 2009
Line 31:		Line 31:

	=== renaming example organization name ===		=== renaming example organization name ===
	[[hCard]] also deliberately re-uses <code>organization-name</code> from [[vCard]] per the [[semantic-xhtml-design-principles]].		* '''organization-name'''. [[hCard]] also deliberately re-uses <code>organization-name</code> from [[vCard]] per the [[semantic-xhtml-design-principles]].

	The unfortunate "clean-up" efforts:		The unfortunate "clean-up" efforts:
	* "company/name" ([[OpenID]] [http://www.axschema.org/types/ attribute exchange] - might also be a renaming of <code>org</code>, see above - how can we be sure?)		* '''company/name''' ([[OpenID]] [http://www.axschema.org/types/ attribute exchange] - might also be a renaming of <code>org</code>, see above - how can we be sure?)
	* "Orgname" ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])		* '''Orgname''' ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])

	=== the Anglo centric renaming anti pattern ===		=== the Anglo centric renaming anti pattern ===

Tantek: /* renaming example org */ added Microsoft VCARD_NAME schema as yet another unnecessary renamer from vCard

2009-06-12T06:25:08Z

renaming example org: added Microsoft VCARD_NAME schema as yet another unnecessary renamer from vCard

← Older revision		Revision as of 06:25, 12 June 2009
Line 22:		Line 22:

	=== renaming example org ===		=== renaming example org ===
	[[hCard]] deliberately re-uses the literal <code>org</code> property name from [[vCard]].		* '''org'''. [[hCard]] deliberately re-uses the literal <code>org</code> property name from [[vCard]].

	On the other hand, the following apparently simple / intended to be helpful renamings have been found:		On the other hand, the following apparently simple / intended to be helpful renamings have been found:
			* '''vCard.Company''' ([http://msdn.microsoft.com/en-us/library/ms535130(VS.85).aspx Microsoft VCARD_NAME schema for AutoComplete functionality])- which can be optimistically interpreted as just "Company"
	* "company/name" ([[OpenID]] [http://www.axschema.org/types/ attribute exchange] - might also be a renaming of <code>organization-name</code>, see below - how can we be sure?)		* '''company/name''' ([[OpenID]] [http://www.axschema.org/types/ attribute exchange] - might also be a renaming of <code>organization-name</code>, see below - how can we be sure?)
	* "organization" (both [http://www.w3.org/2006/vcard/ An Ontology for vCards] and [http://portablecontacts.net/draft-spec.html#organization_element Portable Contacts])		* '''organization''' (both [http://www.w3.org/2006/vcard/ An Ontology for vCards] and [http://portablecontacts.net/draft-spec.html#organization_element Portable Contacts])
	* "affiliation" ([http://google.com/support/webmasters/bin/answer.py?answer=146646 Google contact information properties])		* '''affiliation''' ([http://google.com/support/webmasters/bin/answer.py?answer=146646 Google contact information properties])

	=== renaming example organization name ===		=== renaming example organization name ===

Tantek: added a grouping section as a reminder to avoid renaming when reusing

2009-06-04T01:57:03Z

added a grouping section as a reminder to avoid renaming when reusing

← Older revision		Revision as of 01:57, 4 June 2009
Line 14:		Line 14:
	When reusing the schema or meaning from an existing format, when possible re-use the respective vocabulary as well.		When reusing the schema or meaning from an existing format, when possible re-use the respective vocabulary as well.

	This is particularly important to illustrate, given how often the opposite has occurred (unnecessary renaming/tweaking/abbreviating of existing terms). ~~It happens often enough to merit labeling as an anti-pattern. Examples:~~		This is particularly important to illustrate, given how often the opposite has occurred (unnecessary renaming/tweaking/abbreviating of existing terms).

	=== ~~Example~~ org ===		== avoid renaming when reusing ==
			The renaming of terms when reusing the semantics of an existing format happens often enough to merit labeling as an <span id="avoid_the_Anglo_centric_renaming_anti_pattern">anti-pattern to be avoided</span>.

			Here are some examples:

			=== renaming example org ===
	[[hCard]] deliberately re-uses the literal <code>org</code> property name from [[vCard]].		[[hCard]] deliberately re-uses the literal <code>org</code> property name from [[vCard]].

Line 25:		Line 30:
	* "affiliation" ([http://google.com/support/webmasters/bin/answer.py?answer=146646 Google contact information properties])		* "affiliation" ([http://google.com/support/webmasters/bin/answer.py?answer=146646 Google contact information properties])

	=== ~~Example~~ organization name ===		=== renaming example organization name ===
	[[hCard]] also deliberately re-uses <code>organization-name</code> from [[vCard]] per the [[semantic-xhtml-design-principles]].		[[hCard]] also deliberately re-uses <code>organization-name</code> from [[vCard]] per the [[semantic-xhtml-design-principles]].

Line 32:		Line 37:
	* "Orgname" ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])		* "Orgname" ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])

	=== ~~avoid~~ the Anglo centric renaming anti pattern ===		=== the Anglo centric renaming anti pattern ===
	All of these renamings/expansions/abbreviations may seem (semi-)obvious to English-centric readers, but cause unnecessary confusion when a non-native-English developer encounters different terms that mean the same thing from vCard to these other technologies.		All of these renamings/expansions/abbreviations may seem (semi-)obvious to English-centric readers, but cause unnecessary confusion when a non-native-English developer encounters different terms that mean the same thing from vCard to these other technologies.

	To a non-native-English developer, "org" and "affiliation" are two different sequences of characters, and look as different as "bet" and "nssvyvngvba" do to a non-native-ROT13 developer.		To a non-native-English developer, "org" and "affiliation" are two different sequences of characters, and look as different as "bet" and "nssvyvngvba" do to a non-native-ROT13 developer.

	The unnecessary English renaming of English word properties from earlier standards is an Anglo-centric (specifically English-speaking designer) design mistake that needs to be more thoroughly written up as a design anti-pattern to be avoided. For now we can refer to this problem as the "'''Anglo-centric renaming anti-pattern'''" or just "'''renaming anti-pattern'''" for short.		The unnecessary English renaming of English word properties from earlier standards is an Anglo-centric (specifically English-speaking designer) design mistake that needs to be more thoroughly written up as a design anti-pattern to be avoided.

			For now we can refer to this problem as the <dfn>"'''Anglo-centric renaming anti-pattern'''"</dfn> or just <dfn>"'''renaming anti-pattern'''"</dfn> for short.

	=== more examples ===		=== more examples ===

Tantek: more precisely named the "renaming anti-pattern" (unintendedirony)

2009-06-03T22:20:18Z

more precisely named the "renaming anti-pattern" (unintendedirony)

← Older revision		Revision as of 22:20, 3 June 2009
Line 32:		Line 32:
	* "Orgname" ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])		* "Orgname" ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])

	=== avoid the Anglo centric anti pattern ===		=== avoid the Anglo centric renaming anti pattern ===
	All of these renamings/expansions/abbreviations may seem (semi-)obvious to English-centric readers, but cause unnecessary confusion when a non-native-English developer encounters different terms that mean the same thing from vCard to these other technologies.		All of these renamings/expansions/abbreviations may seem (semi-)obvious to English-centric readers, but cause unnecessary confusion when a non-native-English developer encounters different terms that mean the same thing from vCard to these other technologies.

	To a non-native-English developer, "org" and "affiliation" are two different sequences of characters, and look as different as "bet" and "nssvyvngvba" do to a non-native-ROT13 developer.		To a non-native-English developer, "org" and "affiliation" are two different sequences of characters, and look as different as "bet" and "nssvyvngvba" do to a non-native-ROT13 developer.

	The unnecessary English renaming of English word properties from earlier standards is an Anglo-centric (specifically English-speaking designer) design mistake that needs to be more thoroughly written up as a design anti-pattern to be avoided.		The unnecessary English renaming of English word properties from earlier standards is an Anglo-centric (specifically English-speaking designer) design mistake that needs to be more thoroughly written up as a design anti-pattern to be avoided. For now we can refer to this problem as the "'''Anglo-centric renaming anti-pattern'''" or just "'''renaming anti-pattern'''" for short.

	=== more examples ===		=== more examples ===

Tantek: /* preserve literal vocabulary when reusing meaning */ tweak intro

2009-06-01T21:05:42Z

preserve literal vocabulary when reusing meaning: tweak intro

← Older revision		Revision as of 21:05, 1 June 2009
Line 14:		Line 14:
	When reusing the schema or meaning from an existing format, when possible re-use the respective vocabulary as well.		When reusing the schema or meaning from an existing format, when possible re-use the respective vocabulary as well.

	This particularly important to illustrate, given how often the opposite has occurred (unnecessary renaming/tweaking/abbreviating of existing terms)~~, over and over~~:		This is particularly important to illustrate, given how often the opposite has occurred (unnecessary renaming/tweaking/abbreviating of existing terms). It happens often enough to merit labeling as an anti-pattern. Examples:

	=== Example org ===		=== Example org ===

Tantek: /* benefits */ emphasize new

2009-06-01T21:03:23Z

benefits: emphasize new

← Older revision		Revision as of 21:03, 1 June 2009
Line 7:		Line 7:
	Minimizing the vocabulary used for properties (and values) of a microformat helps make and keep microformats easier to understand.		Minimizing the vocabulary used for properties (and values) of a microformat helps make and keep microformats easier to understand.

	Minimizing the introduction of new vocabulary is particularly important. Doing so:		Minimizing the introduction of ''new'' vocabulary is particularly important. Doing so:
	* Keeps microformats as a whole easier to understand (the smaller the total vocabulary of all microformats).		* Keeps microformats as a whole easier to understand (the smaller the total vocabulary of all microformats).
	* Reduces confusion with the re-use of existing technologies.		* Reduces confusion with the re-use of existing technologies.

	== preserve literal vocabulary when reusing meaning ==		== preserve literal vocabulary when reusing meaning ==

Tantek: drafted

2009-06-01T21:02:44Z

drafted

New page

<entry-title>minimal vocabulary</entry-title>
One aspect of the [[start-simple]] [[microformats]] [[principle]], and one of several [[naming-principles]].

One way of keeping a solution simple is to minimize the vocabulary that the solution uses, and certainly of those, minimize any ''new'' vocabulary that are introduced.

== benefits ==
Minimizing the vocabulary used for properties (and values) of a microformat helps make and keep microformats easier to understand.

Minimizing the introduction of new vocabulary is particularly important. Doing so:
* Keeps microformats as a whole easier to understand (the smaller the total vocabulary of all microformats).
* Reduces confusion with the re-use of existing technologies.

== preserve literal vocabulary when reusing meaning ==
When reusing the schema or meaning from an existing format, when possible re-use the respective vocabulary as well.

This particularly important to illustrate, given how often the opposite has occurred (unnecessary renaming/tweaking/abbreviating of existing terms), over and over:

=== Example org ===
[[hCard]] deliberately re-uses the literal <code>org</code> property name from [[vCard]].

On the other hand, the following apparently simple / intended to be helpful renamings have been found:

* "company/name" ([[OpenID]] [http://www.axschema.org/types/ attribute exchange] - might also be a renaming of <code>organization-name</code>, see below - how can we be sure?)
* "organization" (both [http://www.w3.org/2006/vcard/ An Ontology for vCards] and [http://portablecontacts.net/draft-spec.html#organization_element Portable Contacts])
* "affiliation" ([http://google.com/support/webmasters/bin/answer.py?answer=146646 Google contact information properties])

=== Example organization name ===
[[hCard]] also deliberately re-uses <code>organization-name</code> from [[vCard]] per the [[semantic-xhtml-design-principles]].

The unfortunate "clean-up" efforts:
* "company/name" ([[OpenID]] [http://www.axschema.org/types/ attribute exchange] - might also be a renaming of <code>org</code>, see above - how can we be sure?)
* "Orgname" ([http://www.w3.org/TR/vcard-rdf Representing vCard Objects in RDF/XML])

=== avoid the Anglo centric anti pattern ===
All of these renamings/expansions/abbreviations may seem (semi-)obvious to English-centric readers, but cause unnecessary confusion when a non-native-English developer encounters different terms that mean the same thing from vCard to these other technologies.

To a non-native-English developer, "org" and "affiliation" are two different sequences of characters, and look as different as "bet" and "nssvyvngvba" do to a non-native-ROT13 developer.

The unnecessary English renaming of English word properties from earlier standards is an Anglo-centric (specifically English-speaking designer) design mistake that needs to be more thoroughly written up as a design anti-pattern to be avoided.

=== more examples ===
* See [[rfc-2426#other_variants|other variants of RFC2426]] for more examples of unnecessary property renamings.

== see also ==
* [[naming-principles]]
* [[start-simple]]
* [[principles]]
* [[microformats]]
* [[vCard]]
* [[hCard]]