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

[Tantek Ç elik]

Replying to several messages in this thread in one reply:


On 8/29/07 9:05 AM, "Andy Mabbett" <andy at pigsonthewing.org.uk> wrote:

> 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".

Syntactically the URI would still work, however, semantically it would have
been broken, that is, it is bad to not only change URIs so that they 404 and
just plain don't work, but it is also bad to change the *meaning* of that
URI.  

As Brian pointed out, the URLs for hCard, hCalendar, hReview etc. all *mean*
the *specification*.  Changing that is bad.

However...


On 8/29/07 9:05 AM, "Andy Mabbett" <andy at pigsonthewing.org.uk> wrote:
>
> On Wed, August 29, 2007 16:40, Brian Suda wrote:
>> "... 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.

Rather, let's state this as a positive goal:

Microformats spec pages should be at least as usable as W3C spec pages.

In my experience with web designers and developers, the common feedback I
have heard (and seen, on blog posts etc.) is that W3C specs are opaque and
very difficult to read.

That being said, I'm not necessarily disputing Andy's comparative
evaluation.

I think we can and should set the bar higher - being as usable as W3C specs
is not good enough.

As such, some of the specifics listed would be a good start:

* brief plain-language intro at the top (say for example, something that a
non-technical person like a member of the general media/press could read and
understand)
* followed by links to more plain-language resources

Adding to my to-do list now...


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

I think this is a good pattern to replicate, as it is something that can be
immediately started, and it will make it easier to keep informative
(non-normative) introductory material from bloating up too much the
normative specification (the parts with all the RFC2119 goodness).


>> 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.

You're both right.  We should both be enabling, encouraging discussions
about microformats anywhere on the Web, as well as providing a useful
resource ourselves for people to come learn about microformats.


On 8/29/07 8:51 AM, "Ciaran McNulty" <mail at ciaranmcnulty.com> wrote:

> On 8/29/07, Brian Suda <brian.suda at gmail.com> wrote:
>> --- 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.
> 
> I agree that moving the specs could be confusing, I'd propose either:
>
> ...
> 
> or, preferably
> 
> b) Adding a *-intro page and a small island at the top of the existing
> spec pages that says 'This is a specification, for a quick
> introduction to * see *-intro' or something a bit more user-friendly.

I think the idea of *-intro pages is a very good one.


On 8/29/07 10:40 AM, "Angus McIntyre" <angus at pobox.com> wrote:

> 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, these are excellent specific suggestions for improvement as well,
that I agree with.  I've added them to my to do list for a few
specifications, I expect to learn from the process of adding that material
how to generalize it to microformats specifications in general.

If others have specific suggestions for usability/readability improvements,
please add them to the to-do list:

http://microformats.org/wiki/to-do

Thanks,

Tantek