What are the requirements/problems? Re: Working on New Styles for W3C Specifications

The more I read this thread, the more I get an underlying sense of frustration that what people want is what we currently have because what is broken is _not_ the stylesheet, but the spec as a form of communication and utility itself: that is what needs the redesign (and then the stylesheet, maybe!) .  

Having said that, I share the concerns that people have raised thus far about the redesign (fixed width, cuteness, etc). And I'm still really concerned that what has just been done is a stylistic redesign of what we already have, which I don't think was supposed to be the point of this exercise: i.e., as I said earlier "lets not polish a turd, because it's still going to be a turd!". And I appreciate that we needed to go through this to get to this point: so thank you Vincent for your time doing the redesign.  

I would again ask people to outline what the actual issues are with the specs today. Every designer knows that *form follows function*, and right now I am seeing a lot of change to "form" and little change to "function".  

Let me make this clear again - as someone who is both a daily specification user, implementer, a specification editor (i.e., not as a show off, but as someone whose livelihood absolutely depends on these darn things to pay his bills and feed his family)... in all caps, for communicative effect:  

THE FUNCTION OF THE SPECIFICATION IS BROKEN - *NOT JUST THE FORM* (i.e., not so much the stylesheet).    

Here are some of the problems with the function of the spec (only *some* of the functional issues can be addressed with style changes, others require action by the W3C by changing PubRules, the process document, and possibly things on their HTTP servers):    

1. The *Status of the Document* is still ambiguous and too important to be embedded so far off screen (again, see HTML5 spec for BIG RED NOTE! for how this has already been properly addressed by a *proper design solution that actually fixes a real problem.. today!*). We MUST fix this! The whole status of this document boiler plate needs to be looked at and fixed (with text, icons, whatever… but it needs to be fixed holistically)… one issue is that the status of the document is all over the place: it's at the header level ("Working Draft", "This Version:"), it's also on the top left hand corner, and it's in a section called "Status of This Document": that is just wrong and needs to be consolidated! Patent disclosures, etc., are also important and should also be made obvious. Another huge problem is that when you search the web for a document, sometimes you get the wrong version back from (e.g.,) Google. Also, implementers sometimes implement the wrong version of a spec because of this problem (yes! this really happens… a lot!) because they don't go to the latest version (which is usually the Editor's draft)…. hence why we MUST have a BIG RED FRAAAKEN NOTE AT THE TOP OF THE DOCUMENT (ala HTML5!).   

2. There is cruft at the top of the document (critical bits need to be evaluated and ordered: does it really matter who edited it (are we _that_ egotistical???)? Can we do something about the copyright statement to make people understand what it means? Where is the link to the editor's draft? Where is the link to the test suite?). Ie., how do the poor saps in an office *actually use the spec*? How do they read it? Do they print it? Do they search it with ctr-f and/or use the Table of Contents? Lets organise that stuff visually so it's easier to use so they can do their job: that includes implementing the spec for software engineers, and it might mean searching for useful examples for a web developer.      

3. What do the various stages actually mean (ie., "what the hell is an Editor's Draft anyway?")? How can I actually find out from the document (and not from Google)?  

4. Do we really still need a bibliography when we use hypertext and in the age of living standards? How do people actually use bibliographies in the age of HTML (i.e., do people care when something was published, who published it, etc. and why or why not?)? Can't we just do away with bibliographies and just cross link to specifications.  

Anyway, those are the problems and questions I have. I hope others will also contribute real-world problems that they currently have with the specifications (and not what shade of blue links are, yet).   

--  
Marcos Caceres
http://datadriven.com.au


On Wednesday, 30 November 2011 at 12:00, Robin Berjon wrote:

> Hi Vincent,
>  
> On Nov 29, 2011, at 18:08 , Vincent Hardy wrote:
> > Do you have an example of styling you think is suitable for WebIDL snippets?
>  
>  
>  
> This is just an example, and it does not necessarily carry consensus, but for IDL segments themselves you can look at any API spec that uses ReSpec (which is a large number of them). An example is http://www.w3.org/TR/contacts-api/. It does not necessarily exercise all the styles — I could probably construct a document that does.
>  
> --  
> Robin Berjon - http://berjon.com/ - @robinberjon
>

Received on Thursday, 1 December 2011 17:21:11 UTC