Re: Proposed Quality Tip -- Time in URIs (was URI Usability)

On Apr 14, 2004, at 04:43, Rajasekaran Deepak wrote:
> Proposed quality tip: "Time in URIs"
> <http://students.iiit.net/~deepakr/time-uri/>
> (with '<base href="http://www.w3.org/QA/Tips/" />' and related changes)

Thanks for this contribution.

When reading this draft tip, I come to wonder if the goals of the tips 
have been made very clear. The material in the tip is interesting, but 
there are a few mistakes that probably come from a misunderstanding of 
the idea of quick tips. I hope you won't mind if I use my review of 
your tip to illustrate important principles for the tips.

- Whether people will read the full tip will depend on whether the 
title of the tip is interesting. "Time in URIs" does not excite my 
curiosity, it merely makes me go "uh?". And I guess "dated URIs" may 
be, if not more interesting, at least clearer.

- What's the goal of the tip? A tip is supposed to be an interesting 
tidbit of information, a short "gotcha", something Web 
designers/developers would be eager to learn. What's the purpose of 
"Time in URIs"? We don't know.

- We have to remember that these are "quick tips", not one chapter in a 
larger document. A short introduction is in order.

- The tips are supposed to be helpful bits of information, not 
authoritative, dry specifications. The tips should therefore suggest 
and justify, not slam "must"s at the reader. In our case, with "Time in 
URIs", there is no justification, just two cases and what must be done? 
Why? Why not do the contrary? What's the point? Tips have to be short, 
granted, but too short is just not helpful.

- [corollary] "Must" could be used in a tip when quoting a normative 
specification. If you do, make that clear by using proper quoting 
markup (<blockquote>, <q>). Rewording the normative verbiage may also 
be a good idea if it helps explain the concept.

- Making references to other documents is a good idea, if they develop 
the ideas of the tip, or give techniques, etc. In the case of "Time in 
URIs", why not give a small explanation with the references? Also, I 
don't think all of them, esp. the link to the mail thread, bring a lot 
of value added.

- If making reference to a normative specification, try to explain its 
acronym(s) or give its full name, with the appropriate markup if 
possible. In this case, what's ISO8601? What does it talk about? How is 
it relevant to the tip? is it an ISO standard on dates/time in URIs?


> To the QA Team:
> 1. Kindly link to this tip from <http://www.w3.org/QA/Tips/>.

Although, as you will have noticed from my comments, I do not think 
this tip is mature enough to be published, I am indeed adding this to 
the list of draft tips. I am also removing "URI usability", since it is 
agreed that this document should at least be split in parts before 
being published as a tip.

> 2. I suggest having a one-week review period since the tip "URI 
> Usability"
>     has already been discussed.

"approximately two weeks" is not a rule but a decent approximation of 
how long it usually takes for a tip to be reviewed, no point in making 
an exception here.

Thank you
-- 
olivier