[uf-discuss] Need for plain-language intros for each microformat

[Andy Mabbett]

On Wed, August 29, 2007 16:40, Brian Suda wrote:
> On 8/29/07, Manu Sporny <msporny at digitalbazaar.com> wrote:

[Manu's post hasn't arrived here, yet; I think my ISP has server trouble.]


>> Andy Mabbett wrote:
>>
>>> I think it's time we moved the specs to *-spec or *-specification,
>>> and used the "root" page for each microformat, such as the above, for
>>> a plain-language introduction, taking care to avoid jargon as much as
>>> possible.
>
> --- moving the specs would break links from all over the web and in
> dead tree books that say "you can view the hCard spec at ..." Cool URIs
> don't change. It is probably a better idea create new pages about each
> format and point people to those instead and link the specs to them.

The URI would still work, and a link to the spec could be included "above
the fold".

>> There have been several times where I've pointed
>> somebody to a uF specification page to give them an overview and they
>> just come back claiming that the page didn't really tell them
>> anything... or worse, it confused them.

It seems that this is quite common; it's certainly a problem which needs
to be addressed.

> --- while i agree that a good explication of what hCard, et al are,
> the specs are not always the best place too put this.
>
> "... I've pointed somebody to a uF specification page to give them an
> overview ..."
>
> The simple answer would be to create another overview page and point
> interested people there. When you want to learn more about HTML, do you
> look at the w3c spec or do you look else where?

http://www.w3.org/html/ is not a spec

http://www.w3.org/TR/html401/, while it is a spec, has plain-language
intro and begins with links to more plain-language resources.

Compared to our "root" pages, those are exemplary models of usability.

> what is that else where?
> sometimes it is a primer, or info, or examples, or explanation, or about
> pages, sometimes they are w3c controlled sometimes not.
>
> http://microformats.org/wiki/hcard-overview
> http://microformats.org/wiki/hcard-about
> http://microformats.org/wiki/hcard-primer
> http://microformats.org/wiki/hcard-my-thoughts
> http://microformats.org/wiki/hcard-info
> http://microformats.org/wiki/hcard-explained
>
> could all be candidates for better explaining what an hCard is... as well,

I realised after my initial post that I created
<http://microformats.org/wiki/hcalendar-intro> some time ago.

> it doesn't have to be hosted here. As was pointed out, the wikipedia entry
> is also a good place to explain the explanation and tell people they can
> read that as well.
>
> Microformats are all about bottom-up, we don´t need a central silo for
> "all things microformats". It is OK to have discussions, definitions
> about formats NOT on our wiki.

The microformats wiki is where people come to learn about microformats. We
should serve them.

> I´m all for cleaning things-up and giving more explanations, but this
> shouldn't be to the detriment of the specs and existing links, especially
> when it is so easy to create new pages on the wiki.

No one has suggested doing anything "to the detriment of the specs".

-- 
Andy Mabbett
** via webmail **