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

[Andy Mabbett]

In message <[EMAIL PROTECTED]>, Andy Mabbett
<[EMAIL PROTECTED]> writes

>In message <[EMAIL PROTECTED]>, Tantek Çelik
><[EMAIL PROTECTED]> writes

>>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.
>
>On the contrary, the meaning of the URL would remain the same, and be
>more relevant to the content at that URL. For example:
>
>
>
>is "the wiki page about the hCard microformat", with no reference to
>the specification; that would be:
>
>
>
>
>>As Brian pointed out, the URLs for hCard, hCalendar, hReview etc. all *mean*
>>the *specification*.
>
>That's an assertion, for which you have provided no evidence; I'm
>calling you on it (see also above).

Points neatly underlined by the existence and use of:



-- 
Andy Mabbett
*  Say "NO!" to compulsory UK ID Cards:  
*  Free Our Data:  
*  Are you using Microformats, yet:  ?

___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

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

[John Allsopp]

Andy et. Al.


I have, not for the first time, been told by an "advocacy"  
correspondent

that they have read pages on the wiki, such as
http://microformats.org/wiki/hCard and
http://microformats.org/wiki/hCalendar, and are none-the-wiser as  
to what

microformats in general, and the specific microformats concerned, are.

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.


Should people think that is appropriate (and indeed, I think it is  
certainly a suggestion well worth considering) I'd be more than happy  
to have the content of "know your microformats" be used for, form the  
basis of or otherwise be incorporated into such introductory style  
pages.


http://microformatique.com/?page_id=59

In fact, that was the motivation for their development (they  
constitute an appendix to my microformats book)


thanks

john

John Allsopp

style master :: css editor :: http://westciv.com/style_master
about me :: http://johnfallsopp.com
Web Directions Conferences :: http://webdirections.org
My Microformats book :: http://microformatique.com/book

___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

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

[Andy Mabbett]

In message <[EMAIL PROTECTED]>, Tantek Çelik
<[EMAIL PROTECTED]> writes

>Replying to several messages in this thread in one reply:

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

On the contrary, the meaning of the URL would remain the same, and be
more relevant to the content at that URL. For example:



is "the wiki page about the hCard microformat", with no reference to the
specification; that would be:




>As Brian pointed out, the URLs for hCard, hCalendar, hReview etc. all *mean*
>the *specification*.

That's an assertion, for which you have provided no evidence; I'm
calling you on it (see also above).

>Microformats spec pages should be at least as usable as W3C spec pages.
[...]
>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...

It's not something that only you can do. I'd be quite happy to
contribute a considerable portion, for one.

>If others have specific suggestions for usability/readability improvements,
>please add them to the to-do list:
>
>http://microformats.org/wiki/to-do

*18* months ago:

  


-- 
Andy Mabbett

___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

Re: [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" <[EMAIL PROTECTED]> wrote:

> On Wed, August 29, 2007 16:40, Brian Suda wrote:
>> On 8/29/07, Manu Sporny <[EMAIL PROTECTED]> 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" <[EMAIL PROTECTED]> 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
>  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" <[EMAIL PROTECTED]> wrote:

> On 8/29/07, Brian Suda <[EMAIL PROTECTED]> 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" <[EMAIL PROTECTED]> 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 

Re: [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.
>
>> 
>
> 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

___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

Re: [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 <[EMAIL PROTECTED]> 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
 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 **

___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

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

[Ciaran McNulty]

On 8/29/07, Brian Suda <[EMAIL PROTECTED]> 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:

a) Moving the specs to *-specification and having a big clear note at
the top of the 'root' page directing trafic

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.

-Ciaran McNulty
___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

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

[Brian Suda]

On 8/29/07, Manu Sporny <[EMAIL PROTECTED]> 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.

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

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

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

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.

-brian

-- 
brian suda
http://suda.co.uk

___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss

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

[Manu Sporny]

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.

> 

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.

-- manu
___
microformats-discuss mailing list
microformats-discuss@microformats.org
http://microformats.org/mailman/listinfo/microformats-discuss