Re: code, samp, kbd, var

I have difficulties to follow you where you want to go. Let's take  
the step of the previous mails.

1. I have explained that different "class
    of products" (different implementers)
    need different requirements for
    implementing/using HTML.
2. I explained that the conformance section
    is the tool to give a "table of content",
    a "reading guide" to the specification
    depending on your specific needs.
3. You suggested that specifications are
    too hard for simple HTML users.
4. I suggested, yes, we can improve that by
    writing tutorials.
5. In this mail, you go on saying now that
    people in charge of writing tutorials don't
    understand the specification either.

Let's see where we can go forward *looking for a solution* :) We all  
try to move forward positively.


Le 20 mai 2007 à 10:26, David Woolley a écrit :
> Given the often poor technical quality of user documentation, they  
> can also be use to resolve disputes about correct usage, in which  
> case only a small part of the standard is likely to be read, which  
> is unlikely to be the conformance part.

Yes, some past specifications are difficult to read and not many  
conformance sections have been fully done in the right way. BUT we  
are talking about NOW and a specification which is in development. It  
seems you are one of the ideal candidates to review the new  
specification to make sure that it will be easy to write a tutorial  
or even to join the group who wants to write a tutorial.

Then a proposal: Would you agree to participate in a review. I guess  
it would help a lot the HTML WG.


>> not a tutorial. It is the goal of a specification to be read by  
>> implementers.
>> Now, it doesn't mean that the HTML WG will not produce tutorials, but
>
> Tutorials are probably the least significant type of author  
> documentation; most authors will never read them from cover to  
> cover, but they really need to be read in substantial chunks. The  
> other types are:
>
> - cook books, i.e. samples of code that can be used for common
>   functions without being understood - unfortunately the web
>   itself is one of the main cookbooks!
> - references, which typically describe individual elemens, and
>   may include indexes by functional area; they may also include
>   syntax information, but that is less likely to be read;
> - college lectures, which are becoming more significant and is
>   the only way that most authors will ever receive any
>   structured explanation.

Would you accept to join an effort to produce such documentations  
with other people?



-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Sunday, 20 May 2007 15:37:23 UTC