Re: [MSE] Spec writing guidance for splicing bugs

Aaron Colwell <acolwell@google.com>, 2013-01-31 11:34 -0800:

...
> - What is an acceptable amount of duplication/alternate explanations I
> should have in the spec text?

I'd vote for "none" or "as little as possible" -- for the reasons you
outlined: e.g., If you change the normative text but forget to update any
corresponding non-normative restatement of it you might have included, then
you end up confusing your readers.

> - Who is the MSE spec's primary audience? Implementers or content creators?

I agree with what Paul said in his reply: The primary target for the MSE
spec should be implementors.

> Obviously since Philip, Adrian, and myself are implementers, I've been
> focusing on being precise about the algorithmic aspects and less focused on
> easy to understand higher-level pros descriptions of certain behavior.

I think that focusing on being precise about the algorithmic aspects is the
right way to go. I think the approach you all are following in current MSE
is the right one. The current spec reads the way a spec for implementors
should. I think the goal is to be as precise and unambiguous as possible is
the normative parts of the spec.

> - If alternate explanations are common/expected, will people please provide
> some good examples in other specs that I can draw inspiration from?

The only thing that jumps to mind for me is, there are a few places in the
HTML spec where Hixie has some short sentences that start "In other
words..." to help clarify what a certain step of a particular algorithm is
doing. I really don't think there's usually a need to add anything more
than that.

Where's it's useful to have any kind of alternative explanation, I think
you often end up getting a bug report or comment from somebody asking for
some kind of clarification. So I think it's better to way and add the
clarifications in response to comments like that -- instead of trying to
add additional explanations about things that are already going to be quite
clear to somebody who's reading the spec in the way they should be.

> - Are there other examples of how to clearly mark non-normative sections?
>
> If there are to be alternate explanations that aren't considered normative,
> I'd prefer them not having to be in a giant green box. :)

Yup. I think the way you have the current non-normative parts marked up now
is already better than how most specs handle it. The use of the green
background color for the non-normative parts makes it obvious right away
that they're different.

In summary, I think you all of done a great job of making the MSE spec just
the kind of spec it should be. So keep at it :)

  --Mike

-- 
Michael[tm] Smith http://people.w3.org/mike

Received on Friday, 1 February 2013 06:37:47 UTC