pls avoid "book with user interface" and secret codes

The material in 1.5. Understanding and using this document
http://www.w3.org/TR/qaframe-ops/#understanding-and-using

introduces a *lot* of notational machinery. Is it all
really necessary?

It reminds me of Phil Greenspun's discussion
of the "book with user interface" phenomenon...

[[
The first component of the tech book user interface can be found at the
front of most books: 10 pages explaining which chapters are relevant and
for whom (note that this would not be necessary if the authors were
capable of writing an adequate table of contents). These 10 pages also
usually introduce a whole raft of typographic conventions and icons. The
second component of the user interface is icons strewn throughout a
book. Instead of a blank line and "Note:" in front of a little aside,
you have the big notepad icon (explained in the first 10 pages).
]]
  -- http://philip.greenspun.com/wtr/dead-trees/story.html

Please rely on established notational conventions more and
introduce new devices less.

And regarding...
  Checkpoint 1.1. Commit to at least "QA level three". [Priority 1]

What in the world does that mean?
Please don't introduce a whole collection of secret
codes into the W3C development process.

I first had the "secret code" feeling when reviewing
the changelog. This entry is clear enough:
  Removed Sec 1.3 (Goals of QA Development), revised 1.1, 1.2, 1.4.
because "1.3" is elaborated, but these are inscruitable:
  Clarified fulfillment criteria of CP3.2.
  clean up discussion in CP5.1

Hmm... maybe it's not as bad as I thought... many of the
entries do say what the checkpoint numbers mean...
  Clarified wording of CP3.2 (spec versioning/errata support in TM).
and the changelog is not the highest editorial priority
(though it is important).

Please be sure that the numbers aren't used by themselves
in any important context. e.g. in the status
of this document section, I see

  See QAWG issue #18 and issue #71.

Do your issues have names as well as numbers? If not,
that's a bad sign. Issues without names lead to the
secret code phenomenon... long "issue 71" threads
that newcomers have little hope of penetrating.


-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/

Received on Friday, 29 August 2003 10:59:07 UTC