mailing-lists

From Microformats Wiki
Revision as of 17:53, 31 August 2007 by AndyMabbett (talk | contribs) (make template)
Jump to navigation Jump to search

Mailing Lists

Read the microformats discuss page first.

Then read the mailing list policies.

Then read the respective archives (-discuss, -dev, -new).

After that please see the following additional notes of scope and topics for each list.

Getting subscribed

To subscribe to any of the mailing lists discussed below, please see http://microformats.org/discuss/ - here you will find all relevant subscription links, archives and also access to lists you are already subscribed to where you may change the email address you are subscribed with and the level of emails you will receive (all or digest).

General guidelines

Here is a list of general guidelines to follow in microformats list discussions in general. The overall goal of many of these guidelines is to increase the signal to noise ratio on the lists by encouraging signal, and discouraging noise. Maximizing the signal-to-noise ratio (S/N) is essential to scaling a list membership, and thus as microformats grow in popularity, maximizing S/N becomes more and more important. If you have suggestions for general guidelines, please post them to the microformats-discuss list so that the list-admins may consider your suggestions.

Be nice

AKA Don't be a jerk. This guideline, which may seem totally obvious, is something we need to make explicit because of a few bad examples. The microformats.org community is quite different than both other standards organizations and most open source efforts in (at least) one very important way: this community is a much nicer place to be, with people in general treating each other with a lot of respect and benefit of the doubt. This friendlier tone in the community is something that the community very much values and will fight to defend. See the article Angry/negative people can be bad for your brain for some reasons why. The admins may take swift action to ban or moderate individuals who essentially are "jerks" on the list. Note: neutral tone emails that use simple logical/rational emotion-free language are perfectly fine. This guideline is not a request to add artificial kindness etc. to emails.

Be patient

The community, as part of its broader positive tone, tries to be fairly patient with folks, and we want to continue to encourage that. The microformats lists will always (assuming continued growth and popularity) get new subscribers, and these new subscribers may be unfamiliar with the customs and conventions of the community. As an experienced member in the community, please be patient with new subscribers, and help them improve their behavior by kindly pointing out relevant guidelines and answers on the wiki. However, if it appears that a newcomer has a negative attitude, please raise it to the attention of the admins (offlist) with an official complaint email that references (by email archive URL) or includes the email that demonstrates the negative attitude. Negativity is the biggest exception - this community has very little patience for negativity (see previous Be nice guideline).

Use real world examples

People often invent completely fictitious (and theoretical) examples in order to try to make a point they are trying to make. Microformats themselves are based on studying real world examples and designing for real world examples. Thus arguments based on theoretical examples hold much less weight in microformats discussions and are apt to be ignored. Please avoid posting arguments / questions based solely on theoretical examples.

Ask for real world examples

If someone discusses or provides arguments based on theoretical examples, ask them to provide a real world example and point them to the above guideline.

Use URLs to examples

Please provide URLs to real world examples when possible. This helps to validate that such examples truly are "real world" as they are on the public Web, and provides additional context around the example which might be crucial to understanding it or answering questions about it.

Ask for URLs to examples

When people do not provide a specific URL to a test case or example, then especially as a developer, PLEASE ask them to provide a specific URL (and cite the previous guideline) rather than attempting to work out how an inline snippet of code might work.

Add whitespace to code for readability

In particular, 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. Typical word-wrapping in email does not really improve the readability that much. Please add whitespace (e.g. returns between elements, indentation to indicate element depth) to markup examples when sending in email messages or even when adding to the wiki. Here's a before-and-after example of markup formatting for e-mail.

Avoid replying to yourself to reraise a topic

Especially avoid replying to yourself just to reraise a topic. Please avoid replying to yourself just to "ping" the mailing list or to ask for an update or advice. Especially avoid making assumptions / conclusions simply from the lack of a reply to you or your points. If you really think the issue is of merit, add it to the relevant issues page and just wait for it to be resolved.

Use the wiki to capture state

When re-raising/opening a discussion, please provide a URL to the relevant wiki page which captured the state of the discussion previously. If no such wiki page exists, ask for it. If no one can find it, ask the list for help with researching the previous discussion and creating a wiki page for it. Then put-it-on-the-wiki.

Read FAQs before asking questions

Especially read relevant/respective FAQs before asking questions. Before asking a question on a microformats list, read the relevant FAQs:

  1. Start with the general microformats faq
  2. Then read specific microformats FAQs, e.g. for rel-tag, see the rel-tag FAQ, for adr, see the hCard FAQ as the spec indicates, etc.

Cite URLs to answer questions

When answering questions on a list, cite URL(s) to FAQ answers. Despite the previous guidelines, experience has shown us that there will be time that smart, considerate individuals may attempt to look for an answer on the FAQ, and not find it despite it being there. In such cases, assume that it was a simple unintended oversight (rather than laziness or failure to check the FAQ), and when answering such a question on a microformats list:

  1. Please check the relevant FAQs first, and if the answer is not there, document the question and your answer there. I.e. put-it-on-the-wiki. This is so that the community memory of answers (especially the most recent and accurate state of answers) is kept and grown in a semi-organized and hopefully easily findable fashion on the wiki, rather than deep in the depths of email archives which are often much more difficult to search, and difficult to tell what answer is "the" most recent, relevant and accurate answer.
  2. Cite URL(s) FAQ answer(s) (that you may have just written) rather than just writing an answer, when composing your reply in email. This will hopefully encourage more reading of the wiki and thus learning of answers to microformats related questions in general.

Avoid logical flaws

See logical-flaws for a list of common logical flaws seen on the mailing-list(s) which are to be avoided.

Point out logical flaws

When someone employs one or more known logical-flaws on the mailing-list(s), kindly point out the logical flaw(s), preferably with a link to the specific logical flaw(s).

microformats-discuss

A mailing list for general discussion of microformats, with a strong leaning towards:

  • starting out with microformats
  • real-world content authoring

Good topics for discussion

Here is a list (certainly not definitive) of good topics which are appropriate for the microformats-discuss mailing list:

  • general thoughts on the design and use of semantic XHTML markup
  • how to use and write microformats in content
  • how to use microformat design patterns in content

Good topics that belong somewhere else

Bad topics for discussion

AKA topics better discussed elsewhere (somewhere other than microformats.org).

Here is a list (also not definitive) of topics which are undesired and inappopriate for the microformats-discuss mailing list. In fact, they're not even worth the time to bother discussing, so please do not bring them up on the microformats-discuss mailing list. We'll add more topics as people come up with more off-topic or out-of-scope or rathole topics.

  1. How to make a "general purpose" (micro)format. Go read what microformats are not, actually, go read the entire principles page. Sometimes this may masquerade as a "format of formats". Either way, it is one of those boil the ocean ratholes which are far outside the focus of microformats. If you really want to work on such subjects, teach yourself DTD (SGML, XML), XML Schema, Relax NG, RDF Schema, and find the communities working on those technologies.
  2. Using namespaces and namespace prefixes. In short, namespaces are neither necessary (the Internet ran just fine without them for decades, go read some RFCs), nor desirable (prefixes make formats far uglier and more difficult to hand-code). See also namespaces-considered-harmful.
  3. Using non-English names for properties. This was briefly discussed on the microformats-discuss list most recently as "Language Maps" but has been raised before that. Some folks have raised the issue that microformats use English names for properties, and they would like alternate (non-English) names in other (natural) languages, and perhaps try to establish a mapping between them. As microformats property names are based on existing standards (see process, and naming-principles), this is another problem that is far outside the scope of microformats. As Ryan King put it, this is a pre-existing (unsolved) "problem" with English-based HTML, the English-based CSS, the English-based HTTP and so on. Note that this is NOT about the internationalization (i18n) of the content and data itself - which is of course an excellent goal, advocated and promoted by microformats and the standards they are based on (e.g. W3C, IETF). This is purely about the names of the properties (and enumerated values) in the formats.

microformats-dev

For discussion of microformats development, with a leaning towards:

  • anything that involves writing code
  • abstractions / models (in contrast to actual content)

Good topics for discussion

These tend to be topics that belong in microformats-dev instead of microformats-discuss. This list is also not definitive, but illustrates the general areas:

  • microformat parsing
  • microformat "(auto)-discovery"
  • comparisons of microformats with other data abstractions or data representations (e.g. XML, RDF)
  • compatibility/interoperability of microformats with other data abstractions or data representations

Formerly, the membership to this list was moderated and limited to people who had demonstrated public implementations of microformats. We've since relaxed this requirement, yet maintain the same expectations that people involved in the discussion are focused on concrete and pragmatic topics related to writing code using microformats.

microformats-rest

For discussion of use of microformats with REST, in protocols, services, APIs etc.

microformats-new

This list is for the discussion, exploration and development of new microformats.

This list was created in February 2007 [1] to reduce the new microformat development "noise" on the microformats-discuss list, and allow those that are interested in exploring new microformats to concentrate their efforts.

Specific posting guidelines

  • Make sure you have read and fully understand the process and have already made your website POSH and have used existing microformats as much as you can.
  • Make an effort to search the mailing list archives and the wiki to see if your suggestion has already been made, or is closely related to something in existance. It may be more advisable to build on previous work. See also rejected-formats.
  • Be ready to show plenty of examples of what you're trying to achieve and what real problems you're trying to resolve in the first instance. Suggested formats should expect a certain amount of interrogation about the aim of a new microformat - this shouldn't be taken as negative feedback, or taken personally!
  • Please make a note of any suggested new microformats that do not make it through the process on the rejected-formats wiki page, along with a link to the discussion and the suggested resolution.

Good topics for discussion

  • Discussion on how to re-use existing microformats for "new" uses.
  • Discussion on extension of existing microformats syntax
  • Discussion of the process
  • Development of brand new microformats, adhering to the process

Bad topics for discussion

  • "proposal for a new microformat: hXYZ" - especially if as your first post. Don't send a proposal email as your first email. You're likely to not get very far. In particular, it's also bad form to prematurely name a microformat hXYZ or whatever as well. See Naming consideration. And re-read the entire process.

Unsure

If you are unsure about any of guidelines, or have any other list-specific issues, you are welcome to email the list admins, e.g. for microformat-discuss: email microformats-discuss-owner at microformats dot org.

Help Redirect Topics

If you notice a topic being discussed in one list which would be more appropriate for another list (e.g. discussion of a developer topic like "parsing" in the microformats-discuss list), you can help encourage better list usage by redirecting the thread to the more appropriate list with a gentle reminder at the top, e.g.:

Please redirect discussions of "parsing" and other development related/centric topics to the microformats-dev list per:

http://microformats.org/wiki/mailing-lists#Bad_topics_for_discussion

http://microformats.org/wiki/mailing-lists#microformats-dev

How to search the mailing list archives

If your post to the list starts off "I'm new to the list and microformats so I don't know if you've discussed this already" READ THROUGH THE ARCHIVES!

The archives are getting larger, so here are a few simple ways you can search them. Most popular search engines imploy some sort of site based results filtering. Google does this in your initial search. Type "site:http://microformats.org/discuss/ <search terms here>" to limit the search results to only our discussion list. This will help you from asking a question that has already been posted, debated, and possibly resolved. It saves everyone time and energy!

Gmane provides an alternate search and interface as well as RSS feed for the microformats-discuss list.

Historical

For the record, view our proposals for a new mailing list for discussing the research and creation of new microformats (see "microformats-new" above) so that those discussions do not overwhelm microformats-discuss.

Other

Items regarding the mailing lists that didn't fit anywhere else.