- From: fantasai <fantasai.lists@inkedblade.net>
- Date: Mon, 20 Jun 2011 13:22:22 -0400
- To: www-style@w3.org
On 06/19/2011 01:31 PM, John Daggett wrote:
>
> fantasai wrote:
>
>> This should be fixed once CSS3 Fonts updates to the latest module template. [1]
>
> Hmmm. I'd actually prefer not to write specs that follow this template.
>
> The current structure you've set up is:
>
> TOC
>
> 1. Introduction
>
> 1.1 Background
>
> 1.2 Gobbledygook A
>
> 1.3 Gobbledygook B
>
> 1.4 Gobbledygook C
>
> 2. Actual start of contents
>
> This separates the introduction from the main contents with several
> sections of gobbledygook. This is awful, it's makes it more difficult
> for mere mortals to actually read. Put gobbledygook up above the TOC,
> in an appendix, into it's own special module (CSS Gobbledygook Module
> Level 3?), *anywhere* but in the middle of what normal folks would be
> reading.
The Gobbledygook breaks down into
- 1-2 sentences about how the module interacts with other parts of CSS
- document conventions like what SHOULD/MUST/MAY mean and how non-normative
examples are formatted
- a definition of the <value> syntax
I think these are all necessary for a correct understanding of the rest
of the module. They're gobbledygook to you because you've read enough
CSS specs that all of this is so obvious to you that putting it in writing
is useless and annoying. So skip it. But why should people who are starting
from nothing to not get to this until the end (if they even get there)?
Or not get it at all (separate module)?
Most (all?) technical / tutorial books I've read have an Introduction
chapter which ends with the document conventions. The Introduction explains
what the book is about and why one should read it, and the document
conventions set up the structure for understanding it. I don't see why we
should be any different.
The gobbledygook that should go into an appendix is all the legal/organizational
boilerplate in the Status section. That's not helping anyone except the
lawyers.
> Also, I think it would be a good idea to use the formatting that Vincent
> is using for CSS3 Regions. Our specs have way too many splatterings of
> green and red text.
I think the ideal solution to that would be to get Divya &co to create
a new stylesheet for us and then all switch to using that. It's not just
the red and green text.
~fantasai
Received on Monday, 20 June 2011 17:23:01 UTC