Re: Spec Editing Best Practices

Hi Fantasai and Marcos,

Thanks for working on this! 

Ian

> On Oct 24, 2018, at 10:56 AM, fantasai <fantasai.lists@inkedblade.net> wrote:
> 
> 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
> 

--
Ian Jacobs <ij@w3.org>
https://www.w3.org/People/Jacobs/
Tel: +1 718 260 9447

Received on Monday, 29 October 2018 20:48:20 UTC