Difference between revisions of "examples"

From Microformats Wiki
examples
Jump to navigation Jump to search
m (Reverted edits by ABIDEEN1 (Talk) to last version by Tantek)
Line 1: Line 1:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
<entry-title>Best Practices for Examples Pages</entry-title>
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
'''*-examples''' pages are the first stage of the exploration [[process]] which must precede proposing a new microformat. Current [[Main Page#Exploratory Discussions|explorations]] are listed on the [[Main Page]].   You can use the [[examples-template]] to help you create your own page.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
== Purpose of Example Pages ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
(adapted from [[process]])
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
Document current human behavior on the Web. Remember, we're [http://ifindkarma.typepad.com/relax/2004/12/microformats.html paving the cowpaths]- before you do that you have to ''find'' the cowpaths. Your documentation should be a collection of real world sites and pages which are publishing the kind of data you wish to structure with a microformat. From those pages and sites, you should extract markup examples and the schemas implied therein, and provide analysis.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
== Current Human Behavior on the Web ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
Specifically:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
=== Current ===
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* This is what people are doing '''now''' on the Web.  
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* This is not:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** what people did 50 years ago
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** what you expect people to do in the future
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
=== Human ===
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
Explicit user entered and published information. While automatically published information such as logs from an eletronic thermometer can be interesting, they are not human produced (unless said thermometer is stuck in a human, and that's only indirect/implicit/uncontrolled) and thus do not reflect what humans themselves explicitly do.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
=== Behavior ===
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* What people actually '''do'''. Think empirical evidence, much as in the same way that the scientific method requires gathering of empirical data.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* not:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** what they ''might'' do
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''should have'' done
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''would'' do
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** Intention/Desire/Want. A common mistake done by folks researching background for formats is to explicitly *ask* folks what they *want* or *prefer*, as opposed to *studying* what they *do*. It is well known among behavioral researchers/surveyors that *asking* people what they *want*, or even *asking* people what they *do*, will give you very different (and worse / less accurate) answers than actually *studying* what they *do* in the real world.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** Formats. Formats are prescriptions for behavior, not behavior itself. For documenting formats, create a *-formats page.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
=== Web ===
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* The examples MUST focus on examples actually published on the Web, at a publicly available URL, which should be documented along with the example itself on the wiki page.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* Non-web examples are ok *only* for secondary/tertiary consideration, and by no means outweight (no matter what their quantity etc.) the Web examples.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** private files
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** paper
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** etc.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
== Recommended sections ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
Top level (&lt;entry-title>):
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* Introductory sentence
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
The following items can be used as second level headings == ... ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* purpose
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''What is the purpose of this exploration?''
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''What real world problem(s) / user-scenarios are being solved?''
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* real world examples
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''Links to public web pages, either popular or insightful''
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* analysis of publishing practices
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''Summary and analysis of common patterns discovered from above examples''
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''Other attempts to solve The Problem'' (other actual [[formats]] belong in the *-formats page)
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* see also
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** ''Link to related pages as they become available''
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* next steps
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** *-formats
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
** *-brainstorming
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
Details on specific sections:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
=== real world examples section ===
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* '''Flat list at a minimum.''' The real world examples section should be at a minimum a flat list of examples. See further down for what a good example has.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* '''Grouping into categories can help.''' A giant flat list of examples can sometimes be difficult to navigate and analyze as a whole. Consider grouping related examples into a flat list of categories. If you're not sure how to categorize the examples, or if there are multiple axes across which you could categorize the examples, ask on the [[IRC]] channel or [http://microformats.org/discuss mailing list].
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
== Good Examples of Examples ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
The following pages are some of the best examples of instantiating this design pattern:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* [[review-examples]]
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* [[media-info-examples]]
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* [[blog-post-examples]]
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
== A Good Example Has ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
A good example has several things:
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* URL to the actual example on the Web
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* Link text of that hyperlink should look like a citation of that example, e.g. who, what site
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* Perhaps an illustrative snippet of code (markup) from the example
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
* Analysis of the implied schema represented by that snippet, with at a minimum a flat list of the "fields" present in the example snippet.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
== When Adding Examples ==
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
When adding examples to an existing *-examples page, please try to add the examples into the existing organizational structure in the page. E.g. if the examples are grouped or categorized in a certain way, try to add new examples into those existing categories, instead of a new section.
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
+
If you have to add a new category or subsection, do so, but try to do so in harmony with existing categories. If it is not obvious how to do so, or if the categories don't seem to make sense, then it might be a good time to ask a question on the [[IRC]] channel or [http://microformats.org/discuss mailing list].
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 
MAKE GOD DO WHAT I WANT.MAKE ALLAH DO WHAT I WANT.PUT I TO HEAVEN GOD.PUT I TO HEAVEN ALLAH.
 

Revision as of 00:49, 4 April 2013

<entry-title>Best Practices for Examples Pages</entry-title>

*-examples pages are the first stage of the exploration The microformats process which must precede proposing a new microformat. Current explorations are listed on the Welcome to the microformats wiki!. You can use the *** examples to help you create your own page.

Purpose of Example Pages

(adapted from The microformats process)

Document current human behavior on the Web. Remember, we're paving the cowpaths- before you do that you have to find the cowpaths. Your documentation should be a collection of real world sites and pages which are publishing the kind of data you wish to structure with a microformat. From those pages and sites, you should extract markup examples and the schemas implied therein, and provide analysis.

Current Human Behavior on the Web

Specifically:

Current

  • This is what people are doing now on the Web.
  • This is not:
    • what people did 50 years ago
    • what you expect people to do in the future


Human

Explicit user entered and published information. While automatically published information such as logs from an eletronic thermometer can be interesting, they are not human produced (unless said thermometer is stuck in a human, and that's only indirect/implicit/uncontrolled) and thus do not reflect what humans themselves explicitly do.

Behavior

  • What people actually do. Think empirical evidence, much as in the same way that the scientific method requires gathering of empirical data.
  • not:
    • what they might do
    • should have done
    • would do
    • Intention/Desire/Want. A common mistake done by folks researching background for formats is to explicitly *ask* folks what they *want* or *prefer*, as opposed to *studying* what they *do*. It is well known among behavioral researchers/surveyors that *asking* people what they *want*, or even *asking* people what they *do*, will give you very different (and worse / less accurate) answers than actually *studying* what they *do* in the real world.
    • Formats. Formats are prescriptions for behavior, not behavior itself. For documenting formats, create a *-formats page.

Web

  • The examples MUST focus on examples actually published on the Web, at a publicly available URL, which should be documented along with the example itself on the wiki page.
  • Non-web examples are ok *only* for secondary/tertiary consideration, and by no means outweight (no matter what their quantity etc.) the Web examples.
    • private files
    • paper
    • etc.

Recommended sections

Top level (<entry-title>):

  • Introductory sentence

The following items can be used as second level headings == ... ==

  • purpose
    • What is the purpose of this exploration?
    • What real world problem(s) / user-scenarios are being solved?
  • real world examples
    • Links to public web pages, either popular or insightful
  • analysis of publishing practices
    • Summary and analysis of common patterns discovered from above examples
    • Other attempts to solve The Problem (other actual Best Practices for Formats Pages belong in the *-formats page)
  • see also
    • Link to related pages as they become available
  • next steps
    • *-formats
    • *-brainstorming

Details on specific sections:

real world examples section

  • Flat list at a minimum. The real world examples section should be at a minimum a flat list of examples. See further down for what a good example has.
  • Grouping into categories can help. A giant flat list of examples can sometimes be difficult to navigate and analyze as a whole. Consider grouping related examples into a flat list of categories. If you're not sure how to categorize the examples, or if there are multiple axes across which you could categorize the examples, ask on the #microformats on libera.chat channel or mailing list.

Good Examples of Examples

The following pages are some of the best examples of instantiating this design pattern:

A Good Example Has

A good example has several things:

  • URL to the actual example on the Web
  • Link text of that hyperlink should look like a citation of that example, e.g. who, what site
  • Perhaps an illustrative snippet of code (markup) from the example
  • Analysis of the implied schema represented by that snippet, with at a minimum a flat list of the "fields" present in the example snippet.

When Adding Examples

When adding examples to an existing *-examples page, please try to add the examples into the existing organizational structure in the page. E.g. if the examples are grouped or categorized in a certain way, try to add new examples into those existing categories, instead of a new section.

If you have to add a new category or subsection, do so, but try to do so in harmony with existing categories. If it is not obvious how to do so, or if the categories don't seem to make sense, then it might be a good time to ask a question on the #microformats on libera.chat channel or mailing list.