- From: Karl Dubost <karl@w3.org>
- Date: Tue, 19 Jul 2005 17:00:12 -0400
- To: Bjoern Hoehrmann <derhoermi@gmx.net>, Susan Lesch <lesch@w3.org>
- Cc: www-qa@w3.org
Going though your list:
There are a lot of ways of presenting the same information indeed.
I think we should work with Susan Lesch, if she's ok, to propose
addendum to the [manual of style][1] on the way to present
information for each specification. Then with a kind of analysis
grid, we could try to encourage WGs to modify their markup.
It could have benefits if tools make the life easier too. :)
* Automatic creation of glossary
* Automatic creation of indexes
* Automatic creation of examples
* Automatic creation of schema?
* Testable assertion list requirements
* Automatic nice layout with a predefined "Manual of Style" CSS.
(as in don't bother with it, if you do this markup, it will be like
that)
[1]: http://www.w3.org/2001/06/manual/
My comments are on the fly and not necessary always insightful, it's
more a quick impression. Hope it helps to start
Le 05-07-18 à 18:46, Bjoern Hoehrmann a écrit :
> * http://www.w3.org/TR/2003/REC-SVG11-20030114/
> struct.html#SVGElement
Bad:
* Presentation too technical.
Good:
I would say that a specific page with the full schema and links
as in that one would be good, but not as the main entry point to
understand the feature.
> * http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410/
> abstract_modules.html#s_imagemodule
Good:
* The table model used here is clear to understand the genealogy
and the type.
Element name | Attributes and their types | minimal
content model
Bad:
* List of attributes is difficult to parse automatically,
without having a well defined regex and then prone to errors for
automatic processing.
* Semantics poorly defined or inexistant (even by reference to
another document)
* No examples
* No implementations requirements if any
> * http://www.w3.org/TR/2005/WD-sXBL-20050405/#the-definition
Good:
* systematic in the presentation
* easy to read
Bad:
* Schema in first place is not very helpful, if helpful at all.
The spec is here to understand the features, not to learn how to read
a schema file. Specifically when you come from somewhere else in the
document, you would like first to see the definition and understand
how to use/implement it.
* lacking of examples
> * http://ietfreport.isoc.org/idref/draft-ietf-atompub-format/
Bad:
* Give me a link to an element… How much I respect the work of
IETF, the way the spec are defined is really not usable and all the
converter I have seen so far don't do a good job. :(((
Good:
Text version is useful to cut and paste in a mail but that
should be proposed in an alternate format, not the main format of the
document.
> * http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/#sec-
> CanonicalizationMethod
Good:
* Lot of information
Bad:
* Lot of information
I'm pretty sur all you need is here, but it's almost impossible to
have a quick access to the information and to be able to understand
the main elements of each feature. There's really a layout issue here.
> * http://www.w3.org/TR/1999/REC-xslt-19991116#section-Defining-
> Template-Rules
Good:
* quite clear.
* practical example
Bad:
* Model first.
* difficult to know if it's an example or a the model
* it could have more layout for errors and such things. :)
> * http://relaxng.org/spec-20011203.html#full-syntax
Good:
* We know what we are talking about at the first sentence.
Bad:
* the definition of features later on is lost in a prose without
clear layout
> * http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#element-
> attribute
Good:
* All in one specification: everything accessible ;)
Bad:
* All in one specification: very heavy to download ;)
* Same comment as usual, we start by the technical definition
more than the usage.
> * http://www.w3.org/TR/2005/WD-wsdl20-20050510/#Interface_XMLRep
Good:
* Infoset
Bad:
* Going through the reading, I still don't know what the element
is about.
* Infoset
* Too many links
I'm not sure the Infoset is necessary always a good way to describe
the information or maybe not at least as a first entrance to the
information. I have no strong opinion about that.
> * http://blogs.law.harvard.edu/tech/rss#hrelementsOfLtitemgt
Good:
* The fact to be able to bookmark the element (permalink)
* direct access to what is the purpose of the element
* giving the list of children and their meaning
Bad:
* The permalink is a useless information, but due to User agents
bad implementations for references.
* No access to a formal language definition (schema, DTD, etc)
* conformance requirements sometimes not clear
* I would the link on the element name itself to have more
information and not on "More"
> * http://www.w3.org/TR/1999/REC-html401-19991224/struct/
> global.html#h-7.5.4
Good:
* definition
* example
* presentation of attributes easy to process
* implementation requirements
Bad:
* schema first
> * http://www.w3.org/TR/2005/WD-P3P11-20050701/#ENTITY
Good:
* Definition first
* schema at the end.
Bad:
* I think that the "ENTITY element gives a precise description
of the legal entity making the representation of the privacy
practices." which is repeated almost three times in a row ;)
* lacking example.
> * http://www.ietf.org/rfc/rfc2629.txt
Look above for Atom
> * http://www.w3.org/TR/2005/REC-xkms2-20050628/#XKMS_2_0_Section_7_2
Bad:
* I still don't know what the element is about
* I don't think it's good to put angle brackets around element
in the prose.
> * http://www.w3.org/TR/2005/WD-scxml-20050705/#N103B4
Bad:
* I don't know what the element is about
Good:
* conformance requirements seem good.
> * http://www.w3.org/TR/2003/REC-soap12-part1-20030624/
> #faultdetailelement
Good:
* very clear conformance requirements
* good definition
Bad:
* Lacking example to really understand it
> * http://www.oasis-open.org/committees/download.php/12572/
> OpenDocument-v1.0-os.pdf
Bad:
* PDF
* Schema to define the elements in the prose.
* not many examples
> * http://www.w3.org/TR/2005/REC-SMIL2-20050107/smil-
> timing.html#Timing-SeqSyntax
Good:
* I know it's normative right away
* there's a clear and short definition
Bad:
* I almost missed the end of the definition with excl starting.
It's difficult to see the transition
* not clear what are the attributes
* lacking examples
* Here diagrams could be useful to explain how it's working
> * http://www.w3.org/TR/2003/REC-MathML2-20031021/
> chapter3.html#presm.mi
Good:
* Well not bad at all. It's clear, it flows, there are examples.
Bad:
* Maybe the conformance requirements are not explicit enough
> * https://www.google.com/webmasters/sitemaps/docs/en/
> protocol.html#xmlTagDefinitions
Bad:
* good for a cheatsheet, not for a specification.
> * http://www.w3.org/TR/2005/WD-SVGMobile12-20050413/
> struct.html#SVGElement
For now, it's one of my favourite spec for the layout, except about
the schema and technical definition first.
I would do the opposite.
Usage, Examples, and formal description after.
I really like the presentation for examples and schema. Conformance
requirements are clear.
> * http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo_inline
Good:
* information layout, systematic, description, etc.
* conformance requirements
* Incoming references for properties
Bad:
* Lack of examples
> * http://www.ietf.org/rfc/rfc3920.txt
Same comment
> * http://www.w3.org/TR/2004/WD-emma-20041214/#s3.1.3
Good:
* Clear presentation
Bad:
* Not sure to understand the role
* example has no explaining context.
* attributes not defined by reference. What is an XSD:id
attribute if I'm a newbie.
> * http://www.w3.org/TR/2003/REC-xforms-20031014/slice8.html#ui-
> secret
Good:
* informative
* definition
* example
* requirements are given
Bad:
* Layout special attributes, it gives the feeling of a new
section starting
> * http://www.w3.org/TR/2004/WD-InkML-20040928/#inkElement
Bad:
* angle bracket
* maybe lack of context usage
Good:
* clear layout
--
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***
Received on Tuesday, 19 July 2005 21:00:01 UTC