[css-tables] Editorial: General Comments

A few things up front here...

1. “layouted” is not a word. The past tense of the verb “lay out” is “laid out”.

2. While turning entire sentence predicates into terminology might be the hip
    thing to do in some circles, in CSS we try to define individual nouns and
    (in some cases) verbs for cross-linking. Not only does this look less absurd
    to the lay person, it gives more grammatical flexibility to the referrer,
    focuses highlights on concept-distinguishing content words rather than their
    surrounding sentence-context words, reduces the need for passive construction
    (and thereby the wordiness of sentences in general), and reduces the effort
    necessary to commit terminology to memory and keep its consistent throughout
    the spec.

    For example,
      # A table-root element is said to be <dfn>layouted in collapsed-borders mode</dfn>
    is better as
      | The table is in <dfn>collapsed-borders mode</dfn>

3. CSS layout operates on boxes, not elements. A table-root element is not layouted.
    A table is laid out. The only sections of your spec that should be talking about
    elements are the ones discussing boxes being generated from elements, and those
    making comparisons or examples with HTML *elements*. See
      https://drafts.csswg.org/css-display/#intro

4. The format for defining values of a CSS property is
    <dl dfn-for="property-name" dfn-type="value">
      <dt><dfn>value</dfn>
      <dd>...

      <dt><dfn>other-value</dfn>
      <dd>...
    </dl>

    This will facilitate correct formatting and cross-linking.

    Also, using <dl> instead of a bunch of mixed-up paragraphs with inline definitions
    makes the spec easier to scan. Unlike blog posts, which are meant to be read like
    normal literature, CSS specs must be designed equally for scanning and perusing.
    Part of this effort is in the styling (it is one of the reasons our specs don't
    have a “subtle” look to them), but part of it is also in how we as spec editors
    structure our content.

5. The word “may” MUST NOT appear in your spec except when describing optional
    behavior.

    For example,
      # Lengths may not be negative.
    should be
      | Negative values are invalid.
    or some such unequivocal statement.

~fantasai

Received on Monday, 5 September 2016 22:22:02 UTC