Best Practices for Examples Pages

(Difference between revisions)

Jump to: navigation, search
m (typo)
Current revision (22:44, 1 November 2013) (view source)
(Details of Example Scoping: try improving heading to "What kind of examples and why")
 
(17 intermediate revisions not shown.)
Line 1: Line 1:
-
= Best Practices for Example Pages =
+
<entry-title>Best Practices for Examples Pages</entry-title>
-
'''Example''' 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.
+
'''*-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.
 +
 
 +
== Current Human Behavior on the Web ==
 +
Examples for the development of a microformat {{must}} reflect:
 +
* [[#Current|Current]]
 +
* [[#Human|Human]]
 +
* [[#Behavior|Behavior]]
 +
* on the [[#Web|Web]]
 +
See each of those sections in the reference at the end for what we mean by those and why.
 +
 
 +
== Template of recommended sections ==
 +
A good *-examples page has the <span id="Recommended_sections">following sections</span>, you can think of this like a template:
 +
 
 +
Top level (&lt;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 [[formats]] 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 [[IRC]] channel or [http://microformats.org/discuss mailing list].
 +
 
 +
== Good Examples of Examples ==
 +
The following pages are some of the best examples of instantiating this design pattern:
 +
* [[review-examples]]
 +
* [[media-info-examples]]
 +
* [[blog-post-examples]]
 +
 
 +
== 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 [[IRC]] channel or [http://microformats.org/discuss mailing list].
== Purpose of Example Pages ==
== Purpose of Example Pages ==
Line 8: Line 62:
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.
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.
-
== Current Human Behavior on the Web ==
+
== What kind of examples and why ==
-
 
+
By current human behavior on the web, we mean:
-
Specifically:
+
=== Current ===
=== Current ===
Line 17: Line 70:
** what people did 50 years ago
** what people did 50 years ago
** what you expect people to do in the future
** what you expect people to do in the future
-
 
=== Human ===
=== 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.
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.
Line 39: Line 90:
** etc.
** etc.
-
== Recommended sections ==
+
== See also ==
-
+
* [[examples-examples]]
-
Top level (=):
+
-
* Introductory sentence
+
-
Second level (==):
+
-
* The Problem)
+
-
** ''What is the purpose of this exploration?''
+
-
* Participants
+
-
** ''Bulleted list of who is active (or cares)''
+
-
* Real-World Examples
+
-
** ''Links to public web pages, either popular or insightful''
+
-
* Existing Practices
+
-
** ''Summary of common patterns discovered''
+
-
** ''Other attempts to solve The Problem''
+
-
* See Also / Next Steps
+
-
** ''Link to related pages as they become available''
+
-
*** *-formats
+
-
*** *-brainstorming
+
-
 
+
-
=== 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 [http://microformats.org/discuss mailing list and/or irc channel]
+
-
 
+
-
== Good Examples of Examples ==
+
-
The following pages are some of the best examples of instantiating this design pattern:
+
-
* [[review-examples]]
+
-
* [[media-info-examples]]
+
-
* [[blog-post-examples]]
+
-
 
+
-
== A Good Example Has ==
+
-
 
+
-
A good example has several things:
+
-
* URL to the actual example on the Web
+
-
* Link text of that hyperlink should be 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 [http://microformats.org/discuss mailing list or irc channel].
+

Current revision


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

Contents

Current Human Behavior on the Web

Examples for the development of a microformat MUST reflect:

See each of those sections in the reference at the end for what we mean by those and why.

Template of recommended sections

A good *-examples page has the following sections, you can think of this like a template:

Top level (<entry-title>):

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

Details on specific sections:

real world examples section

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:

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 IRC channel or mailing list.

Purpose of Example Pages

(adapted from 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.

What kind of examples and why

By current human behavior on the web, we mean:

Current

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

Web

See also

Best Practices for Examples Pages was last modified: Friday, November 1st, 2013

Views