hreview-issues: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (→‎Ratings: attrbution)
m (Reverted edits by ABIDEEN10 (Talk) to last version by Tantek)
 
(35 intermediate revisions by 16 users not shown)
Line 1: Line 1:
= hReview issues =
<h1> hReview issues </h1>


These are externally raised issues about [[hreview|hreview]] with broadly varying degrees of merit.  Thus some issues are REJECTED for a number of obvious reasons (but still documented here in case they are re-raised), and others contain longer discussions.  Some issues may be ACCEPTED and perhaps cause changes or improved explanations in the spec.  Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — [http://tantek.com/log/ Tantek]
These are externally raised issues about [[hreview|hReview]] with broadly varying degrees of merit.  Thus some issues are REJECTED for a number of obvious reasons (but still documented here in case they are re-raised), and others contain longer discussions.  Some issues may be ACCEPTED and perhaps cause changes or improved explanations in the spec.   
 
'''IMPORTANT''': Please read the [[hreview-faq|hReview FAQ]] ''before'' giving any feedback or raising any issues as your feedback/issues may already be resolved/answered.
 
Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — [http://tantek.com/ Tantek]
 
Please add new issues to the '''top''' of the list.  Please follow-up to resolved/rejected issues with new information rather than resubmitting such issues.  Duplicate issue additions will be reverted.


See related [[hcalendar-issues]] and [[hcard-issues]].
See related [[hcalendar-issues]] and [[hcard-issues]].


== Template ==
__TOC__
 
== Issues ==
 
=== dtreviewed ===


Please use this format (copy and paste this to the end of the list to add your issues):
*{{OpenIssue}} 2010-04-09 raised by [[User:Aroot|Andy Root]]
* YYYY-MM-DD raised by [http://yourhomepage.example.com YOURNAME].
*# My concern is about the way dtreviewed is handled. It is suggested that the date be wrapped in the <i>abbr</i> tag. Since an ISO8601 absolute date time is NOT a friendly way to represent a date we use the abbr to represent it in a friendly manner. This would makes sense if the <i>abbr</i> tag was intended for that use but it is being used in the opposite manner. The friendly text should be placed in the title attribute and the abbr value should be the unfriendly (usually short) version. When a user mouses over they get the friendly version that helps the user understand the abbreviation. You see the hReview experience is opposite, the user sees an already understandable piece of information being a friendly way to represent a date but when they mouse over it they get a bunch of characters that don't make sense to them. This is not a good user experience not to mention the issues around accessibility.  
*# ''Issue 1: Here is the first issue I have.''
<p>I suggest using the <i>ins</i> tag, which defines text that has been inserted into a document and datetime specifies the date and time when the text was inserted/changed.</p>
*# ''Issue 2: Here is the second issue I have.''
<pre><nowiki>
<ins class="dtreviewed" datetime="20050418">April 18th, 2005</ins>
</nowiki></pre>


== rel=&quot;self&quot; ==
=== rel=&quot;self&quot; ===


2005-01-04 by [[User:DavidJanes|David Janes]]:
OpenIssue 2005-01-04 by [[User:DavidJanes|David Janes]]:


Atom defines rel=&quot;self&quot; [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]
Atom defines rel=&quot;self&quot; [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]
Line 26: Line 38:
Since we're using &quot;bookmark&quot; to mean the entry point to the hReview, isn't the &quot;self&quot; redundant or overly subtle?
Since we're using &quot;bookmark&quot; to mean the entry point to the hReview, isn't the &quot;self&quot; redundant or overly subtle?


== default lower bound ==
=== Multilinguism ===
 
*{{OpenIssue}} 2006-03-22 raised by Fil
*# the reviewer spec can't say ''For anonymous reviews, use "anonymous" (without quotes) for the full name of the reviewer.'' as this word ("anonymous") is going to be apparent on the page, and is not multilingual (and even in English someone might want to use another word, like "an anonymous coward")
 
=== Price ===
* {{OpenIssue}} 2006-04-04 raised by [[User:Evan|Evan]].
*# It doesn't seem possible to give an approximate, average, or absolute '''price''' of the product or service in question. Examples: for a piece of software, the suggested retail price. For a restaurant, average price of an entree, ''or'' a '''price range'''. Prices should almost definitely have a ''currency'' marker and an ''amount''. Suggestion: ''<nowiki><span class="price"><abbr class="currency" title="Canadian dollars">$</abbr><span class="amount">10.99</span></span></nowiki>''. For a range, ''<nowiki><span class="pricerange"><span class="price"> ... </span> to <span class="price"> ... </span></span></nowiki>''.
 
<div class="hentry">
=== Item ===
*{{OpenIssue}} <span class="entry-summary author vcard"> <span class="published"><abbr title="2010-07-10">2010-07-10</abbr></span> raised by <span class="fn">[[User:Codeguru413|Codeguru413]]</span></span>.
<div class="entry-content discussion issues">
* <strong class="entry-title"><abbr title="International Standard Book Number">ISBN</abbr>s should not be used as unique IDs for [[hReview]]s</strong>.
 
As I was reading the spec, I came across the following for the definition of the <b>item</b> portion of [[hReview]]: <i>"Non-<abbr title="Uniform Resource Locator">URL</abbr> unique item IDs (e.g. <abbr title="International Standard Book Number">ISBN</abbr>s, <abbr title="Universal Product Code">UPC</abbr>s) MAY be represented as a <abbr title="Uniform Resource Name">URN</abbr> ("url") for the item."</i> If you look at [http://www.isbn.org ISBN.org]'s website, they warn strongly against using <abbr title="International Standard Book Number">ISBN</abbr>s as unique IDs because often times, a book with the <em><strong>same title</strong></em> may have <em><strong>different</strong></em> <abbr title="International Standard Book Number">ISBN</abbr>s. Often, when we think of a book, what we really mean is a title. A book is just a particular publication of a title. As we know, books for a title can come in many different formats: softcover, hardcover, large print, illustrated, etc. Each publication will have a different <abbr title="International Standard Book Number">ISBN</abbr>.


There is no encoding within the <abbr title="International Standard Book Number">ISBN</abbr> number that accounts for whether a book of a certain title is a softcover or hardcover, rather, merely because they are two separately published items from the same or different publishers, they will have different <abbr title="International Standard Book Number">ISBN</abbr>s. This is especially problematic for [[hReview]] since that microformat is meant for aggregation. It is possible that reviews for a single title will be split across many different <em>books</em> simply because each review is tied to a (possibly) different <abbr title="International Standard Book Number">ISBN</abbr>. This makes it much more difficult to aggregate reviews for such items as books (ahem&mdash;or should I say, <em>titles</em> ;) ).
By using some other way to uniquely identify titles, reviews for titles can be aggregated and displayed for each instance of a title (e.g., a book). I know that unique identifiers are out of scope for [[hReview]]. I'm only suggesting that reviews should not use the <abbr title="International Standard Book Number">ISBN</abbr> of a book as a way to identify the title to which the review refers.
** No follow-up comments have been left yet.
</div>
<div class="hentry">
*{{OpenIssue}}
<span class="entry-summary author vcard">
<span class="published">2010-10-19</span>
raised by <span class="fn">[[User:MarcusJT|Marcus Tucker]]</span>.
</span>
<div class="entry-content discussion issues">
* <strong class="entry-title">Percentages</strong>.
Just as stars (e.g. 3 stars out of 5) are a universal way of representing scores/ratings, so are percentages (e.g. 60%). However, at present percentages aren't mentioned anywhere in the hReview standard, let alone catered for specifically, despite there being countless examples of percentages used for review ratings across the web.
I can't find any trace of discussion relating to the inclusion of percentages in the hReview standard, so for the time being I can only assume that it is an oversight, but I cannot fathom how this could be so.
Anyway, I propose that just as the standard already requires that a number by itself (e.g. 3) should (in the absence of best/worst metadata) be interpreted as 3 out of 5, so a number followed (with or without space) by a percentage sign (e.g. 60%) should be acceptable, as it literally translates to 60 out of 100 (with a minimum of 0), and can be translated to the 1-5 rating format relatively easily, though dealing with percentages of less than 10% needs some thought given the default rating range of 1.0 to 5.0 that hReview currently defines.
''Addendum 2010-11-02: Google's Rich Snippets (which extracts information from hCard, hReview, hCalendar, and other microformats) will happily read a percentage value and display it as a rating out of 5. However, the validity of this approach remains unmentioned here and therefore a response/discussion/guidance/incorporation into the hReview standard is still required.''
</div>
</div>
<div class="hentry">
*{{OpenIssue}}
<span class="entry-summary author vcard">
<span class="published">2010-10-19</span>
raised by <span class="fn">[[User:MarcusJT|Marcus Tucker]]</span>.
</span>
<div class="entry-content discussion issues">
* <strong class="entry-title">hReview does not currently support data stored in VALUE attributes</strong>.
In some situations the rating (or other desired hReview value) may currently be expressed neither as plain text nor TITLE attribute as the standard currently allows for, but instead as a VALUE attribute of a form element, an extreme example being as a VALUE of the (SELECTED) OPTION element of a SELECT element (which unfortunately is the real-world code that I have to work with and cannot completely rework as I would like to due to cost implications).
Alas the current hReview standard does not seem to provide any mechanism for marking up ratings expressed as a VALUE attribute and hence cannot be applied in such situations without significantly altering the structure/format/elements of the HTML - hence I suggest that a third, general solution needs to be devised to permit the use of hReview in such situations (i.e. where an important microformat data value is stored in a VALUE attribute).
</div>
</div>
== Template ==
{{issues-format}}
== Resolved Issues ==
Issues that are resolved but may have outstanding [[to-do]] items.
* ...
== Closed Issues ==
Resolved issues that have no further actions to take.
=== default lower bound ===
* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*#* REJECTED INVALID ASSUMPTION.  Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.
*#* REJECTED INVALID ASSUMPTION.  Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.


== Specification Clarifications ==
=== default range ===
* 2006-02-23 raised by Andy Mabbett
*# ''Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.''
*#* REJECTED IGNORES RESEARCH. Most [[review-examples|real-world examples]] have a range of 1.0-5.0 not a percentage. You may set the "best" bound to 100 explicitly, and the "worst" bound to 0 explicitly per the spec if necessary.
*#* "most" != "all"; indeed, the page you cite has examples of "1-10" and "0-100%". I never claimed that many examples use percentages, but I'm sure a mathematician would explain that values in the range "1-5" may be expressed as percentages.
*#* REJECTED RTFM. Most examples are what the defaults are based on. Please re-read both the spec and the previous resolution, 1-10 is allowed (you have to explicitly set "best" to 10), and so is 0-100 (you have to explicitly set "worst" to 0 and "best" to 100).


=== Specification Clarifications ===
* 2006-02-01 raised by [http://tantek.com Tantek].
* 2006-02-01 raised by [http://tantek.com Tantek].
*# ''The spec needs to clarify that there is only one "item" per "hreview".''
*# ''The spec needs to clarify that there is only one "item" per "hreview".''
*#* ACCEPTED.  Resolved in hReview 0.3.
=== Date and Time ===
* 2006-08-24 raised by [[User:Elias|Elias Sinderson]]
*# ''Issue 1: (This is copied from the hcalendar-issues page, as it applies to hreview as well.) Although ISO 8601 allows both basic (sans delimiters) and extended formats, the extended format (where hyphens and colons are explicitly added) is broadly preferred for the web. While RFC 2445 specifies that the basic form be used in in iCalendar date / time fields, the W3C has published a technical [http://www.w3.org/TR/NOTE-datetime note] (submitted by Reuters), which recommends that the extended (delimited) format be used, and the [http://www.w3.org/TR/html401/types.html#h-6.11 HTML 4.0 spec] uses the extended format. Further, RFC 3339 defines a ISO 8601 profile for dates and time representations on the internet that future specs SHOULD use; recommending a fully delimited representation (see sec. 5.6). Lastly, it should be noted that the [http://www.w3.org/TR/xmlschema-2/#date xsd:date] and [http://www.w3.org/TR/xmlschema-2/#dateTime xsd:dateTime] types are specified as being the ISO 8601 extended format. So, given that hCalendar is based on iCalendar, it is understandable that it allows both formats, however this is clearly a case in which it would be very reasonable to require users to upconvert the format into the least ambiguous and most easily parsed / validated representation. Think of the children.
*#* REJECTED. INCORRECT METHODOLOGY. "Require users to upconvert"??  No.  We optimize for publishers (the "users" in this context) more than developers. Whenever you find yourself saying or even <em>thinking</em> "require users", you're probably thinking along the wrong lines of reasoning.  In particular we have already made the decision/resolution to permit the broader range of datetime values permitted by RFC2445, and explicitly included some shortcuts (e.g. timezone offsets) specifically to make things <em>easier</em> for <em>users</em>.


==Ratings==
==Related pages==
2006-02-23 raised by Andy Mabbett
{{hreview-related-pages}}
Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.

Latest revision as of 04:58, 7 April 2013

hReview issues

These are externally raised issues about hReview with broadly varying degrees of merit. Thus some issues are REJECTED for a number of obvious reasons (but still documented here in case they are re-raised), and others contain longer discussions. Some issues may be ACCEPTED and perhaps cause changes or improved explanations in the spec.

IMPORTANT: Please read the hReview FAQ before giving any feedback or raising any issues as your feedback/issues may already be resolved/answered.

Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — Tantek

Please add new issues to the top of the list. Please follow-up to resolved/rejected issues with new information rather than resubmitting such issues. Duplicate issue additions will be reverted.

See related hcalendar-issues and hcard-issues.

Issues

dtreviewed

  • open issue! 2010-04-09 raised by Andy Root
    1. My concern is about the way dtreviewed is handled. It is suggested that the date be wrapped in the abbr tag. Since an ISO8601 absolute date time is NOT a friendly way to represent a date we use the abbr to represent it in a friendly manner. This would makes sense if the abbr tag was intended for that use but it is being used in the opposite manner. The friendly text should be placed in the title attribute and the abbr value should be the unfriendly (usually short) version. When a user mouses over they get the friendly version that helps the user understand the abbreviation. You see the hReview experience is opposite, the user sees an already understandable piece of information being a friendly way to represent a date but when they mouse over it they get a bunch of characters that don't make sense to them. This is not a good user experience not to mention the issues around accessibility.

I suggest using the ins tag, which defines text that has been inserted into a document and datetime specifies the date and time when the text was inserted/changed.

<ins class="dtreviewed" datetime="20050418">April 18th, 2005</ins>

rel="self"

OpenIssue 2005-01-04 by David Janes:

Atom defines rel="self" here

The value "self" signifies that the IRI in the value of the href attribute identifies a resource equivalent to the containing element.

HTML rel="boomark" here

Refers to a bookmark. A bookmark is a link to a key entry point within an extended document. The title attribute may be used, for example, to label the bookmark. Note that several bookmarks may be defined in each document.

Since we're using "bookmark" to mean the entry point to the hReview, isn't the "self" redundant or overly subtle?

Multilinguism

  • open issue! 2006-03-22 raised by Fil
    1. the reviewer spec can't say For anonymous reviews, use "anonymous" (without quotes) for the full name of the reviewer. as this word ("anonymous") is going to be apparent on the page, and is not multilingual (and even in English someone might want to use another word, like "an anonymous coward")

Price

  • open issue! 2006-04-04 raised by Evan.
    1. It doesn't seem possible to give an approximate, average, or absolute price of the product or service in question. Examples: for a piece of software, the suggested retail price. For a restaurant, average price of an entree, or a price range. Prices should almost definitely have a currency marker and an amount. Suggestion: <span class="price"><abbr class="currency" title="Canadian dollars">$</abbr><span class="amount">10.99</span></span>. For a range, <span class="pricerange"><span class="price"> ... </span> to <span class="price"> ... </span></span>.

Item

  • ISBNs should not be used as unique IDs for hReviews.

As I was reading the spec, I came across the following for the definition of the item portion of hReview: "Non-URL unique item IDs (e.g. ISBNs, UPCs) MAY be represented as a URN ("url") for the item." If you look at ISBN.org's website, they warn strongly against using ISBNs as unique IDs because often times, a book with the same title may have different ISBNs. Often, when we think of a book, what we really mean is a title. A book is just a particular publication of a title. As we know, books for a title can come in many different formats: softcover, hardcover, large print, illustrated, etc. Each publication will have a different ISBN.

There is no encoding within the ISBN number that accounts for whether a book of a certain title is a softcover or hardcover, rather, merely because they are two separately published items from the same or different publishers, they will have different ISBNs. This is especially problematic for hReview since that microformat is meant for aggregation. It is possible that reviews for a single title will be split across many different books simply because each review is tied to a (possibly) different ISBN. This makes it much more difficult to aggregate reviews for such items as books (ahem—or should I say, titles ;) ).

By using some other way to uniquely identify titles, reviews for titles can be aggregated and displayed for each instance of a title (e.g., a book). I know that unique identifiers are out of scope for hReview. I'm only suggesting that reviews should not use the ISBN of a book as a way to identify the title to which the review refers.

    • No follow-up comments have been left yet.


  • open issue!

2010-10-19 
raised by Marcus Tucker.

  • Percentages.

Just as stars (e.g. 3 stars out of 5) are a universal way of representing scores/ratings, so are percentages (e.g. 60%). However, at present percentages aren't mentioned anywhere in the hReview standard, let alone catered for specifically, despite there being countless examples of percentages used for review ratings across the web.

I can't find any trace of discussion relating to the inclusion of percentages in the hReview standard, so for the time being I can only assume that it is an oversight, but I cannot fathom how this could be so.

Anyway, I propose that just as the standard already requires that a number by itself (e.g. 3) should (in the absence of best/worst metadata) be interpreted as 3 out of 5, so a number followed (with or without space) by a percentage sign (e.g. 60%) should be acceptable, as it literally translates to 60 out of 100 (with a minimum of 0), and can be translated to the 1-5 rating format relatively easily, though dealing with percentages of less than 10% needs some thought given the default rating range of 1.0 to 5.0 that hReview currently defines.

Addendum 2010-11-02: Google's Rich Snippets (which extracts information from hCard, hReview, hCalendar, and other microformats) will happily read a percentage value and display it as a rating out of 5. However, the validity of this approach remains unmentioned here and therefore a response/discussion/guidance/incorporation into the hReview standard is still required.


  • open issue!

2010-10-19 
raised by Marcus Tucker.

  • hReview does not currently support data stored in VALUE attributes.

In some situations the rating (or other desired hReview value) may currently be expressed neither as plain text nor TITLE attribute as the standard currently allows for, but instead as a VALUE attribute of a form element, an extreme example being as a VALUE of the (SELECTED) OPTION element of a SELECT element (which unfortunately is the real-world code that I have to work with and cannot completely rework as I would like to due to cost implications).

Alas the current hReview standard does not seem to provide any mechanism for marking up ratings expressed as a VALUE attribute and hence cannot be applied in such situations without significantly altering the structure/format/elements of the HTML - hence I suggest that a third, general solution needs to be devised to permit the use of hReview in such situations (i.e. where an important microformat data value is stored in a VALUE attribute).

Template

Consider using this format (copy and paste this to the end of the list to add your issues; replace ~~~ with an external link if preferred) to report issues or feedback, so that issues can show up in hAtom subscriptions of this issues page. If open issues lack this markup, please add it.

Please post one issue per entry, to make them easier to manage. Avoid combining multiple issues into single reports, as this can confuse or muddle feedback, and puts a burden of separating the discrete issues onto someone else who 1. may not have the time, and 2. may not understand the issue in the same way as the original reporter.

<div class="hentry">
{{OpenIssue}} 
<span class="entry-summary author vcard">
 <span class="published">2011-MM-DD</span> 
 raised by <span class="fn">~~~</span>
</span>
<div class="entry-content discussion issues">
* <strong class="entry-title">«Short title of issue»</strong>. «Description of Issue»
** Follow-up comment #1
** Follow-up comment #2
</div>
</div>

Resolved Issues

Issues that are resolved but may have outstanding to-do items.

  • ...

Closed Issues

Resolved issues that have no further actions to take.

default lower bound

default range

  • 2006-02-23 raised by Andy Mabbett
    1. Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.
      • REJECTED IGNORES RESEARCH. Most real-world examples have a range of 1.0-5.0 not a percentage. You may set the "best" bound to 100 explicitly, and the "worst" bound to 0 explicitly per the spec if necessary.
      • "most" != "all"; indeed, the page you cite has examples of "1-10" and "0-100%". I never claimed that many examples use percentages, but I'm sure a mathematician would explain that values in the range "1-5" may be expressed as percentages.
      • REJECTED RTFM. Most examples are what the defaults are based on. Please re-read both the spec and the previous resolution, 1-10 is allowed (you have to explicitly set "best" to 10), and so is 0-100 (you have to explicitly set "worst" to 0 and "best" to 100).

Specification Clarifications

  • 2006-02-01 raised by Tantek.
    1. The spec needs to clarify that there is only one "item" per "hreview".
      • ACCEPTED. Resolved in hReview 0.3.

Date and Time

  • 2006-08-24 raised by Elias Sinderson
    1. Issue 1: (This is copied from the hcalendar-issues page, as it applies to hreview as well.) Although ISO 8601 allows both basic (sans delimiters) and extended formats, the extended format (where hyphens and colons are explicitly added) is broadly preferred for the web. While RFC 2445 specifies that the basic form be used in in iCalendar date / time fields, the W3C has published a technical note (submitted by Reuters), which recommends that the extended (delimited) format be used, and the HTML 4.0 spec uses the extended format. Further, RFC 3339 defines a ISO 8601 profile for dates and time representations on the internet that future specs SHOULD use; recommending a fully delimited representation (see sec. 5.6). Lastly, it should be noted that the xsd:date and xsd:dateTime types are specified as being the ISO 8601 extended format. So, given that hCalendar is based on iCalendar, it is understandable that it allows both formats, however this is clearly a case in which it would be very reasonable to require users to upconvert the format into the least ambiguous and most easily parsed / validated representation. Think of the children.
      • REJECTED. INCORRECT METHODOLOGY. "Require users to upconvert"?? No. We optimize for publishers (the "users" in this context) more than developers. Whenever you find yourself saying or even thinking "require users", you're probably thinking along the wrong lines of reasoning. In particular we have already made the decision/resolution to permit the broader range of datetime values permitted by RFC2445, and explicitly included some shortcuts (e.g. timezone offsets) specifically to make things easier for users.

Related pages