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

[Angus McIntyre]

On Wed, August 29, 2007 10:59 am, Manu Sporny wrote:
> 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.
>
> +1 for this idea. 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.
>
>> <http://en.wikipedia.org/wiki/Hcard>
>
> The page should be a short introduction and shouldn't overwhelm the
> reader. Perhaps a 1-2 paragraph introduction, a very simple example, and
> links to other wiki pages at the bottom with more information.

+1 for the idea, and for Manu's description of how it should be done. A
well-chosen example up-front would be particularly helpful.

As well as a syntactic example, examples of use would be useful. For
instance, I still have no idea when I might want to use XOXO. Some simple
examples right upfront would probably do a lot to help users figure out
whether a particular microformat is for them or not.

Angus