how-to-play-2

(Difference between revisions)

Jump to: navigation, search
(Sketched out possible sections for new how-to-play)
(First steps of breaking existing how to play rules into sections, reoordering to improve comprehension, reworking some phrasing, making some more concise, and removing references to individuals.)
Line 2: Line 2:
==Sections:==
==Sections:==
 +
 +
As well as rewriting the prose of some of the items to make them more approachable, they also get moved into some clear top-level headings:
* In general
* In general
Line 15: Line 17:
** Link to The Process, but provide brief overview to cover the gotchas of creating new microformats, since some devs will arrive at this page because they want to create a new format.
** Link to The Process, but provide brief overview to cover the gotchas of creating new microformats, since some devs will arrive at this page because they want to create a new format.
-
If this is your first visit, please see the [[introduction]] page.
+
Within those sections, the items themselves are being reordered into something more logical, such that subsections can be added where necessary. The current set-up is pretty much chronological.
-
== Guidelines ==
+
==In General==
-
Before contributing please observe these guidelines:
+
-
# You have to create an account before editing/creating pages. Please consider using your name, e.g. GivenFamily (FirstLast), see also [http://en.wikipedia.org/wiki/Wikipedia:Username Wikipedia Username guidelines]. You may use an alias (e.g. [[User:Adactio]], [[User:Phae]]). Please do not use organization names or other proper nouns (e.g. products, technologies).
+
Thanks for getting involved in microformats development! This page exists to help you find your feet, sets out the methods we use to work productively, along with a few ground rules and expectations. If this is your first visit, please see the [[introduction]] page, too.
-
# Read about microformats.org [[:Category:public_domain_license|Public Domain Declarations]] and please consider adding the [[Template:cc-public-domain-release]] to your User page accordingly to release your contributions to microformats.org before 2008 into the public domain.
+
 
-
# Try the [http://microformats.org/discuss irc channel (preferable) or mailing lists] first (and read the [[mailing-lists]] page before doing so).
+
The most important rule to foster a healthy, productive open community?
-
# If you write something more opinion rather than logically reasoned, sign it with your username - you can easily do so with a datetimestamp in MediaWiki with four tildes, e.g.: <nowiki>~~~~</nowiki>.
+
 
-
#*On the few occasions when it is necessary to edit others signed contributions (as opposed to general content), take care not to change their meaning.
+
1. '''Be nice.'' You are expected, and should expect in return, the people in this community to act positively and treat one another with respect. You should not assume ill-intent in communications; especially in scientific, precise debate as can occur in standards development, you should be careful not to perceive someone's tone aggressively, and should be careful not to give that impression, either.
-
#*If your logically reasoned statement is part of a discussion which disagrees with a previous comment, you may sign it with your username. However signing such statements is both not required, and may detract from the logically reasoned statement standing on its own (related: [[#avoid-personalizing-proposals|avoid personalizing proposals]]), and thus consider leaving such statements unsigned. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
-
# Please only create pages directly relating to [[POSH]], microformats (and [[picoformats]]) on this wiki. [[data-portability]] in line with microformats [[principles]] is also encouraged. Other pages will likely be deleted.
+
2. Microformat documentation (including the specifications) is released into the public domain. This mostly affects content on this wiki, but we encourage complete, open release of as much microformats related material as possible. We ask that users active before 2008 consider adding the [[Template:cc-public-domain-release]] to your User Page to release your contributions to microformats.org prior to 2008 into the public domain.
-
# <span id="naming">Please obey the [[naming-conventions| naming conventions]] for pages. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>] </span>
+
 
-
# Don't use talk pages. See #3. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
# When giving general examples, ensure that you use valid HTML or XHTML
-
# Please try to ensure that you produce valid XHTML.
+
#* Use indentation and line breaks for clarity
-
# When you paste code, add some line breaks at a reasonable width.
+
#* Please wrap lines at 78 characters, so that code can be reproduced (and quoted) within email
-
# Please do not use "?" or other punctuation in the headings - it helps to keep the URLs to their fragment identifiers shorter and easier to read, copy/paste etc. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
-
# <span id="lowercase-headings">Consider using ''lowercase'' words in headings (except for proper nouns), and avoid repeating the page title in headings.  This helps with shortening permalinks to sections (thereby increasing fidelity of URL transfer, e.g. across email), and keeping their URLs ''all'' lowercase makes them easier to type. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]</span>
+
# <span id="avoid-simple-contradictions">'''Please avoid simple contradictory responses'''</span> such as "No" to questions and issues. Instead provide reasoning with information beyond what is provided in the question or issue.
-
# Headings may be explicitly marked up with &lt;h1&gt; &lt;h2&gt; tags etc. in order to avoid having them show up / pollute the Table of Contents. If you find such headings in a page, please <strong style="text-transform:uppercase">do not</strong> change them to "=" or "==" style headings. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
#* Simple contradictions (inverting other statements on a page as if such an inversion was an argument) waste of time, bloat documentation.
-
# Avoid renaming/changing heading text, including even just their capitalization or to comply with above rules that apply to headings. Headings are often used as permalinks, and changing the heading breaks such permalinks that have already been used.  Thus be careful when creating headings.  If you change a heading please leave a <code><nowiki><div id="oldheadingID"></div></nowiki></code> around the new heading with oldHeadingID set to the necessary value to maintain heading permalinks.[<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
 +
# Use <nowiki>example.org</nowiki> for hypothetical URL examples rather than a presumed-fake domain name (which may eventually be registered, used for spam etc.) On the wiki, wrap example domains in <code>&lt;nowiki&gt;</code> elements so that the URLs are not converted into hyperlinks, e.g.: <code><nowiki>&lt;nowiki&gt;http://example.org/&lt;/nowiki&gt;</nowiki></code>.
 +
#* Use different domain suffixes or sub-domains to show interactions between domains: <nowiki>example.net</nowiki> or <nowiki>example.com</nowiki> or <nowiki>foo.example.org</nowiki> and <nowiki>bar.example.org</nowiki>.
 +
 
 +
 
 +
==On the Wiki==
 +
 
 +
# '''Create an account before editing'''. Please consider using your real name, although you may use an alias if you like. Note that usernames need to be of the form <kbd>FirstLast</kbd>, or <kbd>Nick</kbd>. Please ''do not'' use organization names or other proper nouns (e.g. products, technologies) in your username. See also: [http://en.wikipedia.org/wiki/Wikipedia:Username Wikipedia Username guidelines].
 +
 
 +
# Before editing, and in general, '''if in doubt, ask'''. Try the [[irc]] channel or [http://microformats.org/discuss mailing list] if you have questions.
 +
 
 +
# The microformats wiki exists to document microformats and some closely associated technologies and areas, namely [[POSH]], [[picoformats]]. Discussion in directly related areas and applications of microformats (in line with the [[principals|microformats principals]] such as [[data-portability]] is also encouraged. Be aware that off-topic pages may be deleted. If in doubt, ask.
 +
 
 +
# Please use <abbr title="United States">U.S.</abbr> English ([[en-US]]) spelling for English documentation. This is by convention, following the [http://www.w3.org/2001/06/manual/#Spelling W3C Manual of Style Spelling Editorial Guideline]. #* With exception of: Proper native spellings of proper nouns, e.g. "BT Centre", "Business Design Centre, London, UK", "Centre of Canadian Studies".
 +
#* With exception of: Contributions to discussion content (content signed content within <code>&lt;div class="discussion"></code> blocks), which may be spelled in the author's native English.
 +
 
 +
# <span id="naming">You must follow the [[naming-conventions| naming conventions]] when creating pages.</span>
 +
#* You can override the rendered page title to something more verbose if necessary using <code>&lt;entry-title></code> mark-up in the page.
 +
 
 +
# '''Do create stubs or placeholder pages'''. Linking to pages that do not yet exist (e.g. [[this-page-does-not-exist]]) is useful, and indicates intent, and pages not yet created are automatically aggregated on [[Special:WantedPages]]. Manually creating placeholders breaks that functionality.
 +
 
 +
# Please don't add pages to arbitrary MediaWiki Categories. We use a limited number of categories in order to group specifications and drafts (and the category assignments are used to render them differently than other wiki pages, e.g. [[hCard]]).
 +
#* Specifications are categorised <nowiki>[[Category:Specifications]]</code> and draft specifications into <nowiki>[[Category:Draft Specifications]]</nowiki>
 +
#* If you think of additional categories that would help the community, please add them to the [[category-suggestions]] page and seek community feedback.
 +
 
 +
# Use [[rfc-2119#Templates|templates]] for RFC 2119 terms such as {{must}}, as this uses consistent formatting.
 +
 
 +
# References to (X)HTML element names should be lowercase and marked up with <code>code</code> elements, e.g. <nowiki>the <code>input</code> element</nowiki>. (This convention is adopted from the practice used in the [http://www.w3.org/2001/06/manual/ W3C Manual of Style].)
 +
 
 +
# Multi-line code examples should be contained in <code>&lt;source lang="html4strict">…&lt;/source></code> elements — this uses a plug-in in MediaWiki to syntax highlight your code.
 +
 
 +
# '''Avoid global editorial changes / edits'''. Don't make the same or similar edits to numerous pages, (say, more than a dozen or so pages) for editorial reasons. If you have an opinion on how to globally improve something stylistically or editorially on the wiki, please note it to the [[to-do]] page, and engage the community using the microformats-discuss mailing list. Interpret absence of response(s) as disinterest and thus implicit rejection.
 +
 
 +
# Consider waiting at least 10 minutes after the most recent edit before making your own edit. The previous editor may have further edits to make. Waiting a few minutes avoids potential conflicts and confusion.
 +
#* If you plan to make multiple edits to a page, consider using [[Template:inuse]] by placing <code><nowiki>{{Template:inuse}}</nowiki></code> at the head of the page. (Please don't forget to remove it, when you're done!)
 +
 
 +
# When adding your opinion to pages (rather than adding to documentation), you must date and sign your comments with your username (use the <nowiki>--~~~~</nowiki> shorthand to do this). Discussion on the wiki should be threaded in lists, and wrapped in a <code>&lt;div class="discussion"></code> block.
 +
#* You must not alter the meaning of other people's signed comments.
 +
#* You should not personalize proposed documentation such that it detracts from logical reasoning.
 +
 
 +
# Please do not remove apparently <span id="brokenlinks">broken links</span> (404 etc.). If you cannot fix them, instead de-link them by wrapping <code>&lt;nowiki></code> tags around them, and add a note that the link stopped working as of a certain date. This way the context of the documentation is maintained, the person responsible for the links may fixthe problem, and those researching the links can look them up in the [http://archive.org/ Internet Archive].
 +
 
 +
# <span id="avoidsplitting">'''Avoid splitting pages'''.</span> Do not split, divide, sub-divide, or otherwise reorganize pages unless you are one of the primary editors of such pages. You may not understand the intent of the authors/creators for the organization and growth of that content, and by splitting or reorganizing it, you might cause them work and inconvenience. [[Admins]] are responsible for reverting such splits.
 +
#* If you think a page should be reorganized in some way, and are not yourself responsible for it:
 +
#** Add notes in the page in-place where you think splits need to occur, and how you think they should occur, so that the primary author(s) have a chance to see and follow-up with refinements/changes.
 +
#** When deciding how to split pages, consider doing so in ways that both make it easier for people to find information, easier for contributors to add information, and easier for people to iterate the documentation.  See [[how-to-split-pages]] for more details.
 +
 
 +
# In general, avoid doing large "clean-up" operations on the wiki for the same reasons as avoiding splitting pages. You're encouraged to incrementally improve to pages, and work with primary page editors for more substantial changes. [[Admins]] are responsible for reverting large reorganizations of pages.
 +
 
 +
# Note that we don't use the ‘talk pages’ feature of MediaWiki on the microformats wiki as it fragments functionality offered by IRC and the mailing lists, as well as other pages on the wiki.
 +
 
 +
===Need verifying===
 +
 
 +
Some old how-to-play rules based on technical limitations of the wiki, and so worth revisiting since we upgraded.
 +
 
 +
# Please do not use "?" or other punctuation in the headings - it helps to keep the URLs to their fragment identifiers shorter and easier to read, copy/paste etc.
 +
# <span id="lowercase-headings">Consider using ''lowercase'' words in headings (except for proper nouns), and avoid repeating the page title in headings.  This helps with shortening permalinks to sections (thereby increasing fidelity of URL transfer, e.g. across email), and keeping their URLs ''all'' lowercase makes them easier to type.
 +
# Avoid renaming/changing heading text, including even just their capitalization or to comply with above rules that apply to headings. Headings are often used as permalinks, and changing the heading breaks such permalinks that have already been used.  Thus be careful when creating headings.  If you change a heading please leave a <code><nowiki><div id="oldheadingID"></div></nowiki></code> around the new heading with oldHeadingID set to the necessary value to maintain heading permalinks.
 +
<div class='discussion'>
 +
* This seems like it _needs_ a better technical implementation. Not robust at all. Maybe a plug-in for creating permalink anchors? --[[User:BenWard|BenWard]] 09:23, 22 June 2009 (UTC)
 +
</div>
# Start headings with a letter (or underscore a letter doesn't work), in order to generate valid ID attributes on heading elements.
# Start headings with a letter (or underscore a letter doesn't work), in order to generate valid ID attributes on heading elements.
-
# Avoid global editorial wiki changes / edits (e.g. the same or similar edits applied to numerous pages, say, more than a dozen or so pages).  If you have an opinion on how to globally improve something stylistically or editorially on the wiki, please add it to your section on the [[to-do]] page, and then perhaps ask the community using the microformats-discuss mailing list what folks think of it.  Interpret absence of response(s) as disinterest and thus implicit rejection.  Admins may from time to time do global wiki changes to remove spam, repair damage done by other global wiki edits etc.[<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
-
# <span id="avoid-simple-contradictions">Please avoid simple contradictory responses</span> such as "No" to questions and issues. Instead provide at least a short sentence with a reason which provides information beyond what is provided in the question or issue.  Simple contradictions (like just inverting other statements on a page as if such an inversion was an argument), are a waste of time and space and to be avoided.[<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
===No longer applicable===
-
# Do not remove "red links", nor create empty / placeholder "..." pages for them just to make them not red. The red links usefully communicate a need or a desire for that page to exist, and the person expressing that desire may not be the same person that is able to take the time, or has the necessary skill/background to draft such a page.  The links to pages not yet created often serve as an effective (and easy to execute) "to do" list.  Removing those links makes it harder, less convenient to do so. (One exception noted so far: red links to non-existent microformats e.g. "hbib", should be delinked, as it is desirable for it to be harder/less convenient to create new microformats). Finally, as such links do provide information, they are not redundant. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
-
# Please do not add MediaWiki Categories. With the [[wiki-2|upgrade to the wiki]] we have begun using a very limited number of categories in order to present specifications and drafts differently than other wiki pages. For now if you think additional Categories would help the community, please make suggestions on the [[category-suggestions]] page. [<abbr title="guideline created due to one or more actions by Toby Inkster">src:TI</abbr>]. Previously: Do not use the MediaWiki "Categories" mechanism.  As with "Talk" pages, this community does not use all the features of MediaWiki.[<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
-
# Do not create new "User:" links by hand.  User: links should only created as a result of users actually signing their edits with <nowiki>~~~</nowiki> or <nowiki>~~~~</nowiki>.  That way each User: page will correspond to an actual login, rather than accidentally linking to a page which doesn't represent a login. If you see a red link which appears like it ''should'' be a User: link, e.g. <nowiki>[[DavidJanes]]</nowiki>, rather than editing the link in place, create a redirect at the destination of the link to the person's User: page.[<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
# Check "what links here" before moving pages, and fix any links to the page you're moving, if appropriate.
# Check "what links here" before moving pages, and fix any links to the page you're moving, if appropriate.
-
# Please use U.S. English ([[en-US]]) spellings of common words on English microformats pages. This is by convention, following the [http://www.w3.org/2001/06/manual/#Spelling W3C Manual of Style Spelling Editorial Guideline]. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]. Exception: Please use and maintain the proper native spellings of proper nouns, e.g. "BT Centre", "Business Design Centre, London, UK", "Centre of Canadian Studies", etc. [<abbr title="guideline created due to numerous edits by Ameer Dawood">src:AD</abbr>([http://microformats.org/wiki/Special:Contributions/AmeerDawood])]
+
<div class='discussion'>
-
# Use [[rfc-2119#Templates|templates]] for RFC 2119 terms such as {{must}}.
+
* MediaWiki now handles redirects of moved pages. Plus, only admins can move pages, right? --[[User:BenWard|BenWard]] 09:23, 22 June 2009 (UTC)
-
# References to (X)HTML element names should be lowercase and marked up with <nowiki><code>...</code></nowiki>, e.g. the <code>input</code> element. This convention is adopted from the practice used in the [http://www.w3.org/2001/06/manual/ W3C Manual of Style].
+
</div>
-
# Add whitespace to markup examples for readability. Real world markup examples are often whitespace collapsed, often with all the markup/content on a single line of text. Please add whitespace (e.g. returns between elements, indentation to indicate element depth) to markup examples.
+
 
-
# Use <nowiki>example.org</nowiki> for hypothetical URL examples rather than a fake domain name (which may eventually be registered, used for spam etc.). When doing so, be sure to use <code>&lt;nowiki&gt;</code> tags, e.g.: <code><nowiki>&lt;nowiki&gt;http://example.org/&lt;/nowiki&gt;</nowiki></code> so that the URLs are not auto-hyperlinked by MediaWiki. Where interactions between multiple domains need to be illustrated, you may use <nowiki>example.net or example.com</nowiki> or subdomains of <nowiki>example.org like foo.example.org</nowiki>.
+
==On the Mailing Lists==
-
# If you notice that someone is iteratively editing a page (say by watching the IRC channel, or the [[Special:Recentchanges]] page) that you'd like to edit, consider waiting at least 10 minutes after the most recent edit before doing so, as the person iteratively editing the page may have further edits to make, and thus waiting a few minutes would likely save you both time by avoiding potential/likely edit conflicts. Similarly, if you plan to make multiple edits to a page, consider using [[Template:inuse]] by placing '''<nowiki>{{Template:inuse}}</nowiki>''' at the head of the page. Please don't forget to remove it, when you're done! [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
-
# Please do not remove apparently <span id="brokenlinks">broken links</span> (404 etc.). If you cannot fix them, de-link them using <nowiki><nowiki></nowiki> and note (perhaps with a nested list item or parenthetical remark) that the links appear to have stopped working as of a certain date. This way whoever added the links or is responsible for them may discover that they need to fix them, and those researching the links can still look them up in the [http://archive.org/ Internet Archive]. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
-
# <span id="avoid-personalizing-proposals">Avoid labeling proposals with people's names.</span> Instead please label a proposal using a summary of some (perhaps unique) technical aspect of the proposal. The reasons for this are to avoid overly "personalizing" an idea and having the idea be judged (positively or negatively) by the author associated with it rather than the merits of the idea itself, to avoid having criticisms of the idea even remotely appear as if they are criticisms of the person, and to avoid having a specific person feel like they must defend attacks on an idea as if they were attacks on their person. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
==IRC==
-
# <span id="avoidsplitting">Avoid splitting most pages.</span> Do not split, divide, sub-divide, or otherwise reorganize pages unless you are one of the primary authors of such pages. The reason is that you may not understand what the authors/creators of that page had/have in mind for the organization and growth of the content of the page, and by splitting it or reorganizing it, you might actually cause them <strong>more</strong> work and inconvenience, as well as raising the barrier to editing and/or contributing to the page for new folks as well, thus discouraging community participation. [[Admins]] will likely revert such splits. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>([http://microformats.org/wiki?title=to-do&diff=24428&oldid=24400] [http://microformats.org/wiki?title=to-do&diff=24992&oldid=24707])]
+
 
-
# If you do see a need to split a page which you are not one of the primary authors of, first add notes in the page in-place where you think splits need to occur, and how you think they should occur, before making any split, so that the primary author(s) have a chance to see and follow-up with refinements/changes on how the pages should be split. When deciding how to split pages, consider doing so in ways that both make it easier for new contributors to add information, making it easier for people to iterate, and making it easier for people looking from a real world perspective to find the information. See [[how-to-split-pages]] for more details. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>([http://microformats.org/wiki?title=hcard-examples-in-wild&diff=0&oldid=24726])]
+
==Creating Microformats==
-
# In general, avoid doing large "clean up" operations on the wiki for the same reasons as avoiding splitting most pages.  [[Admins]] will likely revert such large re-organizations of pages and encourage incremental improvements, and suggesting larger improvements to the primary page authors. [<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
+
 
 +
# <span id="avoid-personalizing-proposals">'''Avoid labeling proposals with people's names'''.</span> Instead please label a proposal using a summary of some (perhaps unique) technical aspect of the proposal. The reasons for this are to avoid overly "personalizing" an idea and having the idea be judged (positively or negatively) by the author associated with it rather than the merits of the idea itself. Further, this avoids having criticisms of an idea be confused as criticisms of the author.
 +
 
 +
 
 +
 
 +
 
 +
'''Unrefined [[how-to-play]] content that hasn't been moved into the above follows:'''
 +
 
 +
== Guidelines ==
 +
 
 +
 
 +
 
 +
# Do not create new "User:" links by hand. User: links should only created as a result of users actually signing their edits with <nowiki>~~~</nowiki> or <nowiki>~~~~</nowiki>. That way each User: page will correspond to an actual login, rather than accidentally linking to a page which doesn't represent a login. If you see a red link which appears like it ''should'' be a User: link, e.g. <nowiki>[[DavidJanes]]</nowiki>, rather than editing the link in place, create a redirect at the destination of the link to the person's User: page.[<abbr title="guideline created due to one or more actions by Andy Mabbett">src:A</abbr>]
 +
 
 +
 
 +
 
== Accessibility ==
== Accessibility ==
Line 59: Line 133:
== Wiki Cleaning ==
== Wiki Cleaning ==
 +
See [[spam-removal]].
See [[spam-removal]].

Revision as of 09:23, 22 June 2009

This page is a work-in-progress, draft rewrite of how-to-play. The aim is to produce a document that's clearer to newcomers, and better structured in general. The initial version of the page is a direct copy of the current how-to-play, and will be modified from there on.

Contents

Sections:

As well as rewriting the prose of some of the items to make them more approachable, they also get moved into some clear top-level headings:

Within those sections, the items themselves are being reordered into something more logical, such that subsections can be added where necessary. The current set-up is pretty much chronological.

In General

Thanks for getting involved in microformats development! This page exists to help you find your feet, sets out the methods we use to work productively, along with a few ground rules and expectations. If this is your first visit, please see the introduction page, too.

The most important rule to foster a healthy, productive open community?

1. 'Be nice. You are expected, and should expect in return, the people in this community to act positively and treat one another with respect. You should not assume ill-intent in communications; especially in scientific, precise debate as can occur in standards development, you should be careful not to perceive someone's tone aggressively, and should be careful not to give that impression, either.

2. Microformat documentation (including the specifications) is released into the public domain. This mostly affects content on this wiki, but we encourage complete, open release of as much microformats related material as possible. We ask that users active before 2008 consider adding the Template:cc-public-domain-release to your User Page to release your contributions to microformats.org prior to 2008 into the public domain.

  1. When giving general examples, ensure that you use valid HTML or XHTML
    • Use indentation and line breaks for clarity
    • Please wrap lines at 78 characters, so that code can be reproduced (and quoted) within email
  1. Please avoid simple contradictory responses such as "No" to questions and issues. Instead provide reasoning with information beyond what is provided in the question or issue.
    • Simple contradictions (inverting other statements on a page as if such an inversion was an argument) waste of time, bloat documentation.
  1. Use example.org for hypothetical URL examples rather than a presumed-fake domain name (which may eventually be registered, used for spam etc.) On the wiki, wrap example domains in <nowiki> elements so that the URLs are not converted into hyperlinks, e.g.: <nowiki>http://example.org/</nowiki>.
    • Use different domain suffixes or sub-domains to show interactions between domains: example.net or example.com or foo.example.org and bar.example.org.


On the Wiki

  1. Create an account before editing. Please consider using your real name, although you may use an alias if you like. Note that usernames need to be of the form FirstLast, or Nick. Please do not use organization names or other proper nouns (e.g. products, technologies) in your username. See also: Wikipedia Username guidelines.
  1. Before editing, and in general, if in doubt, ask. Try the irc channel or mailing list if you have questions.
  1. The microformats wiki exists to document microformats and some closely associated technologies and areas, namely POSH, picoformats. Discussion in directly related areas and applications of microformats (in line with the microformats principals such as data-portability is also encouraged. Be aware that off-topic pages may be deleted. If in doubt, ask.
  1. Please use U.S. English (en-US) spelling for English documentation. This is by convention, following the W3C Manual of Style Spelling Editorial Guideline. #* With exception of: Proper native spellings of proper nouns, e.g. "BT Centre", "Business Design Centre, London, UK", "Centre of Canadian Studies".
    • With exception of: Contributions to discussion content (content signed content within <div class="discussion"> blocks), which may be spelled in the author's native English.
  1. You must follow the naming conventions when creating pages.
    • You can override the rendered page title to something more verbose if necessary using <entry-title> mark-up in the page.
  1. Do create stubs or placeholder pages. Linking to pages that do not yet exist (e.g. this-page-does-not-exist) is useful, and indicates intent, and pages not yet created are automatically aggregated on Special:WantedPages. Manually creating placeholders breaks that functionality.
  1. Please don't add pages to arbitrary MediaWiki Categories. We use a limited number of categories in order to group specifications and drafts (and the category assignments are used to render them differently than other wiki pages, e.g. hCard).
    • Specifications are categorised [[Category:Specifications]]</code> and draft specifications into <nowiki>[[Category:Draft Specifications]]
    • If you think of additional categories that would help the community, please add them to the category-suggestions page and seek community feedback.
  1. Use templates for RFC 2119 terms such as MUST, as this uses consistent formatting.
  1. References to (X)HTML element names should be lowercase and marked up with code elements, e.g. the <code>input</code> element. (This convention is adopted from the practice used in the W3C Manual of Style.)
  1. Multi-line code examples should be contained in <source lang="html4strict">…</source> elements — this uses a plug-in in MediaWiki to syntax highlight your code.
  1. Avoid global editorial changes / edits. Don't make the same or similar edits to numerous pages, (say, more than a dozen or so pages) for editorial reasons. If you have an opinion on how to globally improve something stylistically or editorially on the wiki, please note it to the to-do page, and engage the community using the microformats-discuss mailing list. Interpret absence of response(s) as disinterest and thus implicit rejection.
  1. Consider waiting at least 10 minutes after the most recent edit before making your own edit. The previous editor may have further edits to make. Waiting a few minutes avoids potential conflicts and confusion.
    • If you plan to make multiple edits to a page, consider using Template:inuse by placing {{Template:inuse}} at the head of the page. (Please don't forget to remove it, when you're done!)
  1. When adding your opinion to pages (rather than adding to documentation), you must date and sign your comments with your username (use the --~~~~ shorthand to do this). Discussion on the wiki should be threaded in lists, and wrapped in a <div class="discussion"> block.
    • You must not alter the meaning of other people's signed comments.
    • You should not personalize proposed documentation such that it detracts from logical reasoning.
  1. Please do not remove apparently broken links (404 etc.). If you cannot fix them, instead de-link them by wrapping <nowiki> tags around them, and add a note that the link stopped working as of a certain date. This way the context of the documentation is maintained, the person responsible for the links may fixthe problem, and those researching the links can look them up in the Internet Archive.
  1. Avoid splitting pages. Do not split, divide, sub-divide, or otherwise reorganize pages unless you are one of the primary editors of such pages. You may not understand the intent of the authors/creators for the organization and growth of that content, and by splitting or reorganizing it, you might cause them work and inconvenience. Admins are responsible for reverting such splits.
    • If you think a page should be reorganized in some way, and are not yourself responsible for it:
      • Add notes in the page in-place where you think splits need to occur, and how you think they should occur, so that the primary author(s) have a chance to see and follow-up with refinements/changes.
      • When deciding how to split pages, consider doing so in ways that both make it easier for people to find information, easier for contributors to add information, and easier for people to iterate the documentation. See how-to-split-pages for more details.
  1. In general, avoid doing large "clean-up" operations on the wiki for the same reasons as avoiding splitting pages. You're encouraged to incrementally improve to pages, and work with primary page editors for more substantial changes. Admins are responsible for reverting large reorganizations of pages.
  1. Note that we don't use the ‘talk pages’ feature of MediaWiki on the microformats wiki as it fragments functionality offered by IRC and the mailing lists, as well as other pages on the wiki.

Need verifying

Some old how-to-play rules based on technical limitations of the wiki, and so worth revisiting since we upgraded.

  1. Please do not use "?" or other punctuation in the headings - it helps to keep the URLs to their fragment identifiers shorter and easier to read, copy/paste etc.
  2. Consider using lowercase words in headings (except for proper nouns), and avoid repeating the page title in headings. This helps with shortening permalinks to sections (thereby increasing fidelity of URL transfer, e.g. across email), and keeping their URLs all lowercase makes them easier to type.
  3. Avoid renaming/changing heading text, including even just their capitalization or to comply with above rules that apply to headings. Headings are often used as permalinks, and changing the heading breaks such permalinks that have already been used. Thus be careful when creating headings. If you change a heading please leave a <div id="oldheadingID"></div> around the new heading with oldHeadingID set to the necessary value to maintain heading permalinks.
  • This seems like it _needs_ a better technical implementation. Not robust at all. Maybe a plug-in for creating permalink anchors? --BenWard 09:23, 22 June 2009 (UTC)
  1. Start headings with a letter (or underscore a letter doesn't work), in order to generate valid ID attributes on heading elements.

No longer applicable

  1. Check "what links here" before moving pages, and fix any links to the page you're moving, if appropriate.
  • MediaWiki now handles redirects of moved pages. Plus, only admins can move pages, right? --BenWard 09:23, 22 June 2009 (UTC)

On the Mailing Lists

IRC

Creating Microformats

  1. Avoid labeling proposals with people's names. Instead please label a proposal using a summary of some (perhaps unique) technical aspect of the proposal. The reasons for this are to avoid overly "personalizing" an idea and having the idea be judged (positively or negatively) by the author associated with it rather than the merits of the idea itself. Further, this avoids having criticisms of an idea be confused as criticisms of the author.



Unrefined how-to-play content that hasn't been moved into the above follows:

Guidelines

  1. Do not create new "User:" links by hand. User: links should only created as a result of users actually signing their edits with ~~~ or ~~~~. That way each User: page will correspond to an actual login, rather than accidentally linking to a page which doesn't represent a login. If you see a red link which appears like it should be a User: link, e.g. [[DavidJanes]], rather than editing the link in place, create a redirect at the destination of the link to the person's User: page.[src:A]



Accessibility

  1. Use upper case for acronyms like HTML but use <strong style="text-transform:uppercase"> to add strength to phrases like "do not". This improves accessibility for people using text-reading software and other assistive technologies ([1] PDF) (list and versions of text-reading software & other agents affected needed).
  2. Do not use styles or write in ways which contravene Web Content Accessibility Guidelines 1.0. For example, do not rely on color alone to convey information; mark up lists and list items properly.

Wiki Cleaning

See spam-removal.

If you see something which you think needs massive cleanup on the wiki, please point it out to admins on the irc channel or microformats-discuss list rather than doing it yourself. [src:A]

Related

how-to-play-2 was last modified: Wednesday, December 31st, 1969

Views