formats - Revision history

Aaronpk: Replace with {{DISPLAYTITLE:}}

2020-07-18T16:22:41Z

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

← Older revision		Revision as of 16:22, 18 July 2020
Line 1:		Line 1:
	~~<entry-title>~~Best Practices for Formats Pages~~</entry-title>~~		{{DISPLAYTITLE:Best Practices for Formats Pages}}

	'''*-formats''' pages are the second stage of the exploration [[process]] which must precede proposing a new microformat. Current [[Main Page#Exploratory Discussions\|explorations]] are listed on the [[Main Page]]. <!-- TBI: You can use the [[formats-template]] to help you create your own page. -->		'''*-formats''' pages are the second stage of the exploration [[process]] which must precede proposing a new microformat. Current [[Main Page#Exploratory Discussions\|explorations]] are listed on the [[Main Page]]. <!-- TBI: You can use the [[formats-template]] to help you create your own page. -->

Tantek: see also

2012-10-03T21:07:49Z

Tantek: draft

2012-10-03T21:07:03Z

draft

New page

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

'''*-formats''' pages are the second stage of the exploration [[process]] which must precede proposing a new microformat. Current [[Main Page#Exploratory Discussions|explorations]] are listed on the [[Main Page]]. 

== Purpose of Formats Pages ==
Documenting previous formats that have attempted to solve the same problem is useful for several reasons:

* Build on top of others' work and research
* Figure what the (if any) reasons were for previous formats' failures (lack of adoption, or abandonment)
* Take note of what features were used (or ignored) in previous formats
* Determined what else mattered (and what didn't) in previous formats efforts
* Look at previous formats for concepts and names to re-use to minimize invention (per the [[principles]]).

See the [[process]] for more.

== Recommended sections ==
Top level (<entry-title>):
* Introductory sentence
The following items can be used as second level headings == ... ==
* previous formats
** ''Links to specifications of formats that solve the same or similar problems''
* analysis of previous formats
** ''Summary and analysis of previous formats, per the purpose of listed above''
* see also
** ''Link to related pages as they become available''
* next steps
** *-brainstorming

Details on specific sections:

=== previous formats section ===
* '''Flat list at a minimum.''' The previous formats section should be at a minimum a flat list of formats linking to their specifications.

== Good Examples of Formats Pages ==
The following pages are some of the best examples of instantiating this design pattern:
* [[review-formats]]
* [[resume-formats]]

== A Good Format Reference Has ==
A good format reference has several things:
* URL to the actual format specification on the Web
* Link text of that hyperlink should be the common name of the format (abbreviated if that's what is common)
* Perhaps an illustrative snippet of code (markup) from the format
* Analysis of the schema represented by the format, e.g. with a flat list of the "fields" or properties present in the format (perhaps clustered by commonly used, sometimes used, rarely if ever used).

== When Adding Formats ==

When adding examples to an existing *-formats page, please try to add the formats into the existing organizational structure in the page. E.g. if the formats are grouped or categorized in a certain way, try to add new formats 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 formats. 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].

← Older revision		Revision as of 21:07, 3 October 2012
Line 49:		Line 49:

	If you have to add a new category or subsection, do so, but try to do so in harmony with existing formats. 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].		If you have to add a new category or subsection, do so, but try to do so in harmony with existing formats. 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].

			== See Also ==
			* [[examples]]
			* [[principles]]
			* [[process]]