As part of the design of a new generation for the QaFramework, the QA WG decided to put a strong focus on usability of the documents. This is a tentative analysis of what needs to be taken into account when this gets applied to the Specification Guidelines. Discussion of this topic is welcomed on www-qa-wg@w3.org .

Usability focus

The intended audience of SpecGL is, in order of priority:

W3C Specifications editors, in direct contact with the specification writing
W3C WG, responsible for the design of technologies and their incarnation in specifications
reviewers of W3C Specifications, if they need guidance on assessing the quality of a given specification with regard to the principles we're setting

If we try and focus on usability, every design decision we take for the new generation of SpecGL must be evaluated against the benefits for our audience. To evaluate these benefits, it's also important to keep in mind the use cases that we want to enable.

User profiles

Specifications editors

Let's consider our first target, the specifications editors, and see what characteristic they have we should keep in mind:

Specifications editors are busy: in most cases, editing a specification isn't the sole/main job that the editor has ; it needs to optimize the time he/she spends writing, but also reading any sort of rules/guidelines he may be asked to follow
Specifications editors are under pressure to get the job done : they don't want to be the bottleneck of their WG advancement
Specifications editors range from newbie to veterans: some have participated in many specifications and probably don't like too much to be said what to do; others have never done so before, but have been chosen by their WG chair due to their language fluency, their good understanding of the technology or their willingness to help - they may be looking for a step by step guide on how to write a specification
Specifications editors like to see who else has done something similar (e.g., look at examples) and be able to capitalize on this by copying or modifying pieces of code, structure, examples, etc. --LynneRosenthal
Specifications editors want to be proud of their work : having their names on a W3C Technical Report is important for them as a recognition of their work, and the most praise they get from this work, the best for them
Specifications editors (as other WG participants) do not necessarily share our concerns with regard to interoperability or conformance, or don't think/know these can be addressed by the way the specification is written

W3C WG

A WG is not a person but a group of persons, so we need to be careful in evalualating its characteristics. Some may need to be retargetted to specific roles in the WG (chair, team contact, test task force). (this profile can probably be somewhat re-used for testgl and the handbook)

a WG is under several pressures : features creep (everyone wants its specific feature in the spec), time to market (this should have been done yesterday), process burden (still 4212 issues to be resolved) - it won't take on additional pressure if not mandated to, or if it doesn't remove some existing pressure ; besides, they prefer being convinced rather than being mandated
WG participants have often a hard time keeping up with the work done by their own working group, they're unlikely to spend a lot of time on other WG works
WG participants may be very focussed on a given topic, and may not be interested in too abstract or foreign subjects

Spec Reviewers

When reviewing a specification, one doesn't want to have to re-read 20 pages before reading the document - just give them a clear checklist, and they'll figure.

Requirements for spec gl

Brainstorming on what requirements this implies for specgl:

keep it short and simple
avoid to put too much self-documentation constraint (ala "identify this or that")

       -- I don't understand what that bullet means.  Example?  --LoftonHenderson
       -- in the CR version of SpecGL, we had as requirement "Identify all the discretionary item and document them in the conformance section" ; I'm saying that documenting this kind of stuff would be seen as a loss of time by spec editors, and that we should instead just draw attention to these points, rather than requiring to document them --DomHazael

make it a good read
include lots of examples --LynneRosenthal
try suggesting best practices, but keep the door open to new methods
insist on how and why specgl can make the job of writing specifications faster
Show small techniques to make it useful and benefitial for the editor.

QA

Discussion

I'm so fascinated by what the W3C is writing about, but I can't understand why the W3C writes so poorly.

I don't understand why W3C specs are so stiff, boring, and unreadable.

I mean, just look at the page QaFramework:

 The [WWW]W3C Quality Assurance Working Group is working on a new version of its framework for enhancing the quality of W3C Working Groups deliverables, more specifically specifications and test materials. (see [WWW]how the wiki fits in the QA WG's work)

Must we really enhance the quality of W3C Working Groups deliverables, more specificaly specifications and test materials? Why can't we just improve W3C Working Group documents, such as specifications and test materials?

Reading through W3C documents, I always feel like there must be some sort of automated RDF-to-W3C-lingo translator behind the scenes. It feels like the goal is to systemitize the authoring of W3C documents, so that every document that comes out is uniformly bad. Bad, but at least uniformly so. There seems to be an intolerance for some specs being written well, and some specs being written poorly.

Why is this? Is there some distrust of personality (or person-hood) showing through in documents?

I really want to know: Why must writing be so bad? Why can't groups just write what they think, how they think it, in a way that is humane and good? I can understand that documents need a consistent form. Color schemes and logos should be the same, and headers should look pretty much the same. But I think that if the culture allowed a little person-hood into the documents, they'd jump by leaps and bounds in readability.

-- LionKimbro DateTime(2004-06-26T05:25:26)