Re: [css3-2d-transforms][css3-images] <position> grammar is duplicated or points to the wrong spec

On Thu, Feb 2, 2012 at 10:02 AM, Brian Manthos <brianman@microsoft.com> wrote:
>> I've captured precisely that in the wiki as a design principle.  It
>> wouldn't be captured in a CSS spec, because it has nothing to do with
>> CSS-as-it-is-used - it's a design principle that we as spec authors
>> need to follow.
>
> Going OT slightly...
>
> Haven't we had prior discussions where it became abundantly clear that the spirit and intent of the design not being up-front to authors is one of the problems that needs to be addressed?
>
> As such, shouldn't the design principles be documented *within* the specification perhaps as an appendix.
>
> For example, when reading a CSS2.1 spec that a CSS3 spec is based on there are often "surprises" from a literal reading of the text.  Then someone raises a question on this (apparently high traffic) alias asking for clarity and the answer comes back "oh, that was a minor adjustment in CSS2.1 because CSS1 was written by candle light and so ...."  Relying on (a modern analog of) oral tradition to understand the specification's literal text as well as its intent seems a mistake to me.  Lastly, it would be nice to *see* the shift in design principles from 1 to 2 to 2.1 to 3 -- both for the completion of 3, and with an eye toward planning what shifts will be necessary for 4.
>
> A wiki can be a great place to collaborate and build consensus, but capturing a snapshot of the current design principles *with* each specification seems an appropriate additional step.

Yes, explaining some design decisions is important for clarity,
particularly when they can be captured in examples.

However, capturing *every* design principle is unrealistic - there's
no reason to copypaste the design principles behind at-rules into the
List spec, for example.  If following one of them led to a
particularly unintuitive design, it should be documented, but not if
it's a fairly normal thing.

~TJ

Received on Thursday, 2 February 2012 18:27:15 UTC