Re: Comments on W3C Manual of Style

Björn Höhrmann wrote:

>  XHTML source:
>
>    * to increase interoperability, it should use UTF-8 as character
>      encoding. It's questionable whether the XML declaration should be
>      included in the document, if the character encoding is UTF-8, since
>      IE6 will only without switch to compliance mode.

I will have to check into this.

>    * The document RECOMMENDs usage of XHTML 1.0 Strict, the document
>      itself declares it as XHTML 1.0 Strict. The good reason is...?

You mean Transitional. The 'bgcolor' attribute in the XML example needs
transitional. I think using transitional is preferable to having a
manual that won't validate as strict.

http://www.w3.org/2001/06/manual/#Appearance

>    * The style element includes comment delimiters. In XHTML this will
>      cause, that the style sheet will be ignored, since comments get
>      stripped.

Fixed.

>  |   5.2 Translations
>
>  |    First person pronouns ("I," "we") which are hard to translate
>  |    SHOULD NOT be used. See [PRONOUNS]. Avoid "my" and "me" in
>  |    examples (e.g., use "userResource" and not "myResource").
>
>  Specifications should not directly address the reader aswell.
>  Translating second person singluar pronouns is a hard task if the
>  language distinguishes between various forms (like formal and informal)
>  of translations for "you", hence avoid using "you".

I quoted you. :-)

>  |     9.1.2 Document Identification
>
>  |    Access privileges for documents in /TR/YYYY space are
>  |    controlled by ACLs.
>
>  ACL? I thought initialisms should be expanded on first occurence? ;-)

Sorry, that's Access Control List. Fixed.

>  There are more instances of undefined initialisms/acronyms/abbreviations
>  in this document, please take a look at it.

To do.

>  |   9.5 References
>
>  |        Markup for the example above:
>  | <dl>
>  | <dt>[HTML4]</dt>
>  |
>  | <dd><cite><a
>  | href="http://www.w3.org/TR/1999/REC-html401-19991224/">HTML 4.01
>  | Specification</a></cite>, D. Raggett, A. Le Hors, and I. Jacobs,
>  | Editors. World Wide Web Consortium, 17 December 1997, revised
>  | 24 April 1998, revised 24 December 1999. This version of the HTML 4.01
>  | Recommendation is http://www.w3.org/TR/1998/REC-html40-19980424. The
>  | <a href="http://www.w3.org/TR/html4/">latest version of HTML 4</a>
>  | is available at http://www.w3.org/TR/html4.</dd>
>  | </dl>
>
>  This misses some anchor identifier. If references are links, some anchor
>  is required.

Fixed. Good catch.

>  |   11.2 Spelling
>  |
>  |      * Spell-checking using a US English dictionary is REQUIRED.
>
>  Available tools? Mention ispell?

Done.

>  |   11.5 Linking
>  |
>  |      * Unless intentionally referring to the latest document in a
>  |        series, always refer to specific W3C documents by using
>  |        the "this version" URI.
>  |      * URIs should not include a trailing ".html" or other
>  |        extension because this is not part of the document
>  |        identifier.
>
>  ... unless intentionally referring to a specific version of a document
>  (e.g. a gif image where gif and png are available through content
>  negotiation).

Quoted you, thanks.

>  |      * Omit trailing slashes from visible URIs but include them
>  |        in href attributes and link elements. This saves the
>  |        machine from having to make an extra round trip and the
>  |        reader will be free of excessive punctuation.
>
>  I don't like this one. If saving machine resources is a good thing, why
>  should readers be educated to use the URI that doesn't? I think this is
>  a disservice to the reader, /TR and /TR/ don't have to be the same
>  thing, but W3C documents would imply otherwise.

For now, I left this as is, current W3C usage.

>  |   11.8 Markup
>
>  |      * alt text describing the function of all images MUST be
>  |        present and typo-free. Use alt="" for purely decorative
>  |        images that do not add meaning to the page.
>
>  No, not in the first place. If it is possible to write a text that
>  replaces the image (read, alternate text), this should be done in favour
>  to a description of the function of the image.

Fixed. Quoted you.

>  |      * Use the longdesc attribute for important graphics and
>  |        ASCII art, or explain them inline.
>
>  The longdesc attribute can still be used to link to the inline
>  explanatory text (if not inline == in some bitmap image).

Would you explain that again? Sorry I don't quite understand.

>  |      * Use the lang attribute for language change within a page.
>
>  xml:lang

Fixed.

>  |      * Links with the anchor text "Click here" MUST NOT be used.
>  |        They make no sense on setups without mice or similar input
>  |        devices.
>
>  That's a rather bad reasoning. The main issue is that 'click here' is
>  bad hypertext, you dunno where 'here' should be and the link provides no
>  context information; especially it cannot be used without context, while
>  the Style Guide for Online HyperText (IIRC) says they should.

Fixed (I hope).

>  |   11.9 Large Documents
>  |
>  |    Large single files that may be easy to print may not be easy
>  |    to download. For large documents, you SHOULD:
>  |     1. Divide the document logically, storing chapters in
>  |        separate files. Refer to compound documents.
>  |     2. Offer an archived version (zip, tgz) of the separate
>  |        files.
>  |     3. Offer a single, printable version of the specification.
>  |        This format may be compressed if too large.
>
>  IMO, *all* technical reports SHOULD provide archived versions,
>  especially if they are not made of only a single file (e.g.,
>  have images). Archived versions MUST provide all necessary files,
>  especially they should include the relevant WD/CR/PR/REC/...
>  style sheet and MUST NOT link images or style sheets not included
>  in the archive.
>
>  It might be quite common in North America to be connected 24/7 to the
>  internet and thus offline reading just doesn't matter, but e.g. in
>  Europe Internet connection fees are high and rated on a per-minute base,
>  so offline reading is quite vital for many readers. Do them a favour and
>  provide archived versions whenever possible and make them work
>  (providing an archived copy is nice, but if the files link e.g. to the
>  REC.css style sheet, users will encounter many difficulties).

Fixed.

>  | 12. Confusing Terms
>  |
>  |    W3C has reviewed its technical reports one by one since
>  |    November 1999, for typographical errors. The following words
>  |    appear repeatedly in those reviews and are easily confused.
>  |
>  |    anti-alias
>  |           hyphenate
>  |
>  |    ASCII
>  |           all caps
>
>  Better US-ASCII if refering to the character encoding. US-ASCII is the
>  preferred MIME name.

Maybe it would help to know that this came up in reference to the ASCII
standard and ASCII art rather than encoding.

Thank you for your comments!

Received on Sunday, 28 October 2001 01:47:49 UTC