Re: [i18n-html-tech] Some editorial comments

* Richard Ishida wrote:
>>   Phrases like "According to the HTML specification ..." leave some
>>   doubt whether the statement holds true in practise, the document
>>   should rather just tell the facts and if considered useful add a
>>   reference to the relevant section in the specification, like (see
>>   <a>Section Foo in the Bar specification</a>).
>
>If you are referring to the use in
>http://www.w3.org/TR/i18n-html-tech/Overview.html#ri20030218.131104811 ,
>there is some doubt in my mind, still to be clarified by testing, as to
>whether this holds in practise - esp in IE, so I'm currently hedging until I
>can say something clearer like you suggest.  I will add a link there,
>though.

There are several other occurences of similar phrasing (I count seven)
and I would like to see all of them changed at least once the document
enters last call. I would general prefer authoritative statements with
an editors note like "How true is this" as already done in some places
though.

>> No ampersands!
>> 
>>   Headings like "Document structure & metadata" look odd, use "and"
>>   unless you really refer to the & character (like in XML character
>>   references).
>
>As a native speaker it doesn't look odd to me, and it makes for faster
>reading, so I'm not convinced on this one.

It's not faster for me, I have to translate the '&' to "and" which
interrupts the perception of the text and I acutally do not perform the
intended translation, I translate it to "'n'" as in AT'n'T vs. "A.T.
and T.". I think using ampersands in titles is quite uncommon for
Technical Reports and I know that a number of style guidelines advise
against using them unless necessary. I've asked Susan Lesch what the CMS
say in this regard and probably add something about it in the W3C Manual
of Style.

>> Use meaningful anchors!
>> 
>>   To simplify linking the document anchors should be short, easy to
>>   memorize and access. Rather than
>> 
>>    http://www.w3.org/TR/i18n-html-tech/#ri20030218.131051562
>>
>>  It should be e.g.
>>
>>    http://www.w3.org/TR/i18n-html-tech/#use-unicode
>
>Don't want to do this is because it will take me much longer to edit the
>document (these ids are produced by a single keypress), and because the
>content is changing so much at the moment that any persistent meaningful
>names on one day could become misleading names on another.  

If I want to evangelize the document and its guidelines I would need to
have the URI to the respective section handy since just pointing people
at http://www.w3.org/TR/i18n-html-tech/ is unkind and less effective.
This is simple if the sections have meaningful anchors since I can
remember referring to #use-unicode if I want to tell people they should
use Unicode for their pages. In fact, I could just say something like

  PS: You should <http://www.w3.org/TR/i18n-html-tech/#use-unicode>.

Anchors like #ri20030218.131051562 would require that I load the TR in
my browser, search for the section and copy the URI to the clipboard.
This might not be possible if I am not online (and until recently I
wrote all my mails and Usenet postings offline), hence I would probably
be better off if I store a local copy of the document which is already
difficult due to external references to style sheets, etc. Even then,
loading the browser just to get the proper URI might work a few times,
after that it becomes frustrating and I would stop referring to the
document. I've already been through that for the "Quality Tips for
Webmasters" which were originally at <http://www.w3.org/2001/06tips/>,
I could not remember those magic numbers and it's been difficult to find
the document through browsing, so I did not mention them. It's now due
to my request at <http://www.w3.org/QA/Tips/>; Quality Assurance Tips at
/QA/Tips/ - great!

>The techniques themselves are stored in xml rather than html with the aim of
>potentially re-using a given technique in any number of html views
>constructed using XSLT.  Since we don't know what document(s) a technique
>will end up in, it has to have a universally unique id across all this data.
>The currently used format for ids aims to achieve that.

I could live with such anchors names until the document reaches Last
Call, but from that point the benefit of simple linkage outweights the
benefits of rock solid global uniqueness and ease of maintenance in my
opinion.

>This is a very good idea, that I will implement.

Great! Thanks.

Received on Thursday, 26 February 2004 03:35:12 UTC