Re: Organization of techniques document

Jutta Treviranus wrote:
> 
> While acknowledging that the primary task is to get some content for the
> document, we have been giving some thought to the structure of the
> Techniques document.
> 
> Here are some thoughts. I propose that each checkpoint in the document have
> the following sections:
> 
> 1. Criteria for Implementation
> The checkpoints in ATAG are still fairly high level, in talking to
> developers, several of them mentioned that they needed further specifics
> about how to comply. These criteria would be the verifiable criteria that
> apply to all tools. They would differ from the suggested implementations in
> that they are not suggestions, they are all actual "sub-checkpoints."
> 
> Examples of these would be:
> The same fonts, text sizes, colors, symbols, etc. that characterize other
> program features should also characterize those dealing with accessibility.

I don't like the idea of sub-checkpoints. If you know what you
want specifically for conformance, create a checkpoint for it. If you
don't really know what you want, leave the checkpoint vague and clarify
in the techniques document. The ATAG 1.0 has few checkpoints and they
are high level. If more concrete checkpoints are required, add them as
first-class checkpoints. 

If a checkpoint is so high level as to not be useful, make it a
Guideline.

If possible, I would like all the guidelines to use the same model:
guidelines/checkpoints/techniques. I don't know what a level
of subcheckpoints adds. It may confuse readers further.
 
> 2. Suggested Implementations
> These would be examples we imagine of really good implementations. Ideally
> we should illustrate in this section how the checkpoint would be
> implemented in various classes of tools. For example how would you
> implement this checkpoint in a conversion tool, a courseware tool, an HTML
> editor or a WYSIWYG tool. These are not actual implementations, so there
> would not be any compromises or gaps in the implementations. If at all
> possible we should try to include illustrations.
> 
> 3. Sample Implementations
> Here we would discuss and illustrate real world implementations of the
> checkpoint. Within this section we should critique what is done well and
> discuss what could be done better.
> 
> 4. Relevant Documents
> Here we would link in other relevant documents. However, we may link to
> other documents in the other sections if those documents provide the
> content for the sections e.g., the ERT document for Suggested
> Implementations of 4.1 and 4.2.
> 
> Since this is going to be a fairly hefty document, I also propose that we
> allow different views of the document. So a graphic editor developer could
> get the graphic editor view of the document which would leave out the
> examples and checkpoints that don't apply.

Up to now, I was under the impression that people wanted everything
in one document (e.g., sample information is available in the techniques
document and in separate documents). You might split along the following
lines:

 - General techniques, list of resources, links to other techniques
documents
   (this would be the "main" techniques document).
 - Content techniques
 - User interface techniques
 - Sample implementations

 - Ian


-- 
Ian Jacobs (jacobs@w3.org)   http://www.w3.org/People/Jacobs
Cell:                        +1 917 450-8783

Received on Wednesday, 8 March 2000 14:49:58 UTC