[restyle-content] Boilerplate Contents: Requirements and Recommendations

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[restyle-content] Boilerplate Contents: Requirements and Recommendations

fantasai
Ok, so Tantek and Vincent and I sat down and compiled a list of all the bits
of boilerplate in the W3C spec template and all the common meta sections that
specs are expected to contain. We put a rough draft on the W3C wiki here:
   http://www.w3.org/wiki/SpecProd/Restyle/Content
I took a first cut at identifying the primary audience for each piece.

Please review the list and add any notes / corrections. :) Once we have the
raw material compiled for what needs to go in there, we can start looking
at how to organize it, structurally and graphically.

~fantasai

Reply | Threaded
Open this post in threaded view
|

Re: [restyle-content] Boilerplate Contents: Requirements and Recommendations

Robin Berjon-2
On Dec 13, 2011, at 01:26 , fantasai wrote:
> Ok, so Tantek and Vincent and I sat down and compiled a list of all the bits
> of boilerplate in the W3C spec template and all the common meta sections that
> specs are expected to contain. We put a rough draft on the W3C wiki here:
>  http://www.w3.org/wiki/SpecProd/Restyle/Content
> I took a first cut at identifying the primary audience for each piece.

Thanks, this is useful. I don't know if you wish to list all potential statuses that a document may have, but if so the list is longer than the one in the wiki. A longer list is at:

    http://respec.specifiction.com/guide/essential-boilerplate.html#specification-status

You list test suites as CR/REC, but we should make sure that they can be listed earlier if needed.

I wonder if it would make sense to list chairs and team contacts, or if we should rather make sure that they are more prominently listed on group pages. The use case for this is that there are regularly people who need to get in touch about specific technology but don't want to do so through the public list (e.g. a company considering joining a group or the W3C and needing extra info). They often report having had trouble figuring out the proper team+chairs contact (and those are the ones who eventually did find it — we don't know about those who gave up).

I'm not certain that the PP/Disclosures is just for lawyers. The details are, but I think a broader audience is interested in knowing that a specification is RF. This could perhaps be supported with an RF icon, with a link to further details for lawyers.

If the status disclaimer is aimed at people who are new to reading W3C specs (which is the right audience IMHO) then it should be one sentence clearly called out and not something lost in an impenetrable block of text.

--
Robin Berjon - http://berjon.com/ - @robinberjon


Reply | Threaded
Open this post in threaded view
|

Re: [restyle-content] Boilerplate Contents: Requirements and Recommendations

Marcos Caceres-4


On Tuesday, December 13, 2011 at 11:13 AM, Robin Berjon wrote:

> On Dec 13, 2011, at 01:26 , fantasai wrote:
> > Ok, so Tantek and Vincent and I sat down and compiled a list of all the bits
> > of boilerplate in the W3C spec template and all the common meta sections that
> > specs are expected to contain. We put a rough draft on the W3C wiki here:
> > http://www.w3.org/wiki/SpecProd/Restyle/Content
> > I took a first cut at identifying the primary audience for each piece.
>  

I amended:

Use Cases and Requirements | required | Reviewers and Director of W3C |  
Explain what problems trying to solve. Explicitly required by W3C Director to progress specification to CR.


 
> Thanks, this is useful. I don't know if you wish to list all potential statuses that a document may have, but if so the list is longer than the one in the wiki. A longer list is at:
>  
> http://respec.specifiction.com/guide/essential-boilerplate.html#specification-status
>  
> You list test suites as CR/REC, but we should make sure that they can be listed earlier if needed.
>  
> I wonder if it would make sense to list chairs and team contacts, or if we should rather make sure that they are more prominently listed on group pages. The use case for this is that there are regularly people who need to get in touch about specific technology but don't want to do so through the public list (e.g. a company considering joining a group or the W3C and needing extra info). They often report having had trouble figuring out the proper team+chairs contact (and those are the ones who eventually did find it — we don't know about those who gave up).

I agree. I get a lot of emails that I then use to pass onto team contacts or the WG Chair. The mailing list should also be listed in the header. The Editors should be de-emphasize or removed from the header, to encourage people to send information to the mailing list instead.  
 
> I'm not certain that the PP/Disclosures is just for lawyers. The details are, but I think a broader audience is interested in knowing that a specification is RF. This could perhaps be supported with an RF icon, with a link to further details for lawyers.

I agree.  
>  
> If the status disclaimer is aimed at people who are new to reading W3C specs (which is the right audience IMHO) then it should be one sentence clearly called out and not something lost in an impenetrable block of text.
I also agree.