W3C home > Mailing lists > Public > spec-prod@w3.org > October to December 2001

Comments on W3C Manual of Style

From: Bjoern Hoehrmann <derhoermi@gmx.net>
Date: Sun, 21 Oct 2001 01:14:48 +0200
To: spec-prod@w3.org
Cc: lesch@w3.org
Message-ID: <b6s3tts0nlg92cuagi20ipr427bv5bs8m8@4ax.com>

Some comments on <http://www.w3.org/2001/06/manual/>. It's great work in
general, but there are some issues left.

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.

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

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

|   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".

|     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? ;-)
There are more instances of undefined initialisms/acronyms/abbreviations
in this document, please take a look at it.

|   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.

|   11.2 Spelling
|      * Spell-checking using a US English dictionary is REQUIRED.

Available tools? Mention ispell?

|   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

|      * 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.

|   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.

|      * 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).

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


|      * 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.

|   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).

| 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.

Björn Höhrmann { mailto:bjoern@hoehrmann.de } http://www.bjoernsworld.de
am Badedeich 7 } Telefon: +49(0)4667/981028 { http://bjoern.hoehrmann.de
25899 Dagebüll { PGP Pub. KeyID: 0xA4357E78 } http://www.learn.to/quote/
Received on Saturday, 20 October 2001 19:15:53 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:42:16 UTC