Re: [uf-discuss] Need for plain-language intros for each microformat
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: http://microformats.org/wiki/hcard is the wiki page about the hCard microformat, with no reference to the specification; that would be: http://microformats.org/wiki/hcard-specification 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: http://microformats.org/wiki/XFN -- Andy Mabbett * Say NO! to compulsory UK ID Cards: http://www.no2id.net/ * Free Our Data: http://www.freeourdata.org.uk * Are you using Microformats, yet: http://microformats.org/ ? ___ 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
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 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 [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 material how to generalize it to microformats specifications in general. If others have specific suggestions for
Re: [uf-discuss] Need for plain-language intros for each microformat
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: http://microformats.org/wiki/hcard is the wiki page about the hCard microformat, with no reference to the specification; that would be: http://microformats.org/wiki/hcard-specification 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: http://microformats.org/discuss/mail/microformats-discuss/2006-February/003068.html -- 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
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 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. -- manu ___ 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
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
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 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 ** ___ 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
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 ___ microformats-discuss mailing list microformats-discuss@microformats.org http://microformats.org/mailman/listinfo/microformats-discuss
