Spec Editing Best Practices

Marcos and I led a TPAC breakout session about spec editing best practices.
Here's a summary of the points:

Spec Organization and Prose
---------------------------

1. Define the overall model of the technology and shape of the problem
    before defining the API and technical details.

2. Start with an overview / high-level description, push fiddly details
    and more boring material further down in the section, so that a reader
    gets an overall understanding before adding details and so that authors
    can stop reading once they get bored and have read everything they need.

3. Algorithmic vs Constraint based spec approaches: understand which to
    use when -- they each have their strengths and weaknesses, and you
    can use either or both as appropriate.

4. Use diagrams/figures/examples generously to illustrate, but not replace,
    normative prose.

5. Keep examples and figures close to the point they're illustrating.

6. Use the Infra data types and literals when you need to reference data
    types in the abstract. https://infra.spec.whatwg.org/

7. Periodically read your spec from top to bottom, to make sure it makes
    sense when read in order.

8. Also review your table of contents:
      * Ensure the spec and its heading structure is well-organized
      * Have headings (and thus the TOC links) use evocative language
        (not just titled by bits of code) to help readers quickly find
        the right section from the TOC.
      * Be generous with subheadings, to break up long sections and
        facilitate linking and easier ToC usage.

Spec Tooling / Formatting
-------------------------

1. Use version control.

2. Use a preprocessor like ReSpec or Bikeshed:
      https://tabatkins.github.io/bikeshed/
      https://github.com/w3c/respec/wiki

3. Use manual IDs so that IDs remain stable as you adjust the heading text;
    add old IDs (via empty elements with IDs, or e.g. Bikeshed's oldids attribute)
    when removing or changing IDs so that links to your spec don't break.

4. Consider semantic line breaks:
      http://rhodesmill.org/brandon/2012/one-sentence-per-line/
    (We looked at the source code to CSS Grid as an example*, see
     https://github.com/w3c/csswg-drafts/blob/master/css-grid-1/Overview.bs )

Extra
-----

1. A spec editor has to address every comment. Part of this is responding
    back to the commenter. Be sure to respond to each issue with:
    * Summary of the WG decision
    * Link to changes or new spec prose, if any
    * Rationale for the decision
    * Invitation to respond with any further concerns


* If you want to use Tab-and-fantasai style source code formatting, it's:
    - Tabs for indentation, spaces for alignment.
    - Semantic line breaks: at phrases boundaries, each line < ~80ch
    - Indent the entire spec one level except for headings.
    - Line break after opening heading tag, so heading text is easy to pick
      out when scanning the source.
    - Empty lines between blocks.
    - Indent contents of block-level HTML elements (except <p>, which we
      usually imply via Markdown formatting and otherwise leave inlined
      at the start of the paragraph). Definitely leave a break and indent
      after any block start tag with attributes, though.
    - No optional end tags.

~fantasai

Received on Wednesday, 24 October 2018 15:56:52 UTC