Re: [TR] Status Section Requirements

This is a section dear to my heart.

When we started W3C, a major model was the IETF,
and IETF drafts, but IETF drafts had very boilerplate SOTDs.
So I wanted the SOTD to be human readable and exactly what
an intelligent reader perhaps from another group would need
to know -- the the editor how its going, get a 5-second verbal
elevator version, and then point out that that should be the SOTD.

Something like

"This is a draft which we really expect to be the last unless
some new controversy breaks out over the whatchamacallit"

or "No point commenting on this really except section 3,
as we are going to rip out everything else."

That is the spirit I suspect of the process document
document's requirement to have a paragraph which is unique.
Yes, you have to think, and that adds effort to publishing 
a document.

[below...]



On 2013-10 -31, at 07:22, fantasai wrote:

> # Every document published as part of the technical report development
> # process must clearly indicate its maturity level, and must include a
> # section about the status of the document. The status section
> #
> #  1. must be unique each time a specification is published,
> #  2. must state who developed the specification,
> #  3. must state how to send comments or file bugs, and where these are recorded,
> #  4. should explain how the technology relates to existing international
> #       standards and related work inside or outside W3C,
> #  5. should include expectations about next steps, and
> #  6. should explain or link to an explanation of significant changes
> #      from the previous version.
> 
> First Issue
> ------------
> 
> 2, 3, 4, and 6 are fine requirements, but should not be required
> by the Process to show up in the status section. These are things
> that are best moved out of the status section (along with much of
> the boilerplate) into their own positions in the document template.
> This isn't the case at the moment, but let's not have the Process
> become a blocker on improving the document template. :)

It makes sense to completely separate boilerplate
things actually written to express something.


> 
> Second Issue
> ------------
> 
> 1 is generally not followed. Most status sections are complete
> boilerplate. Even if they weren't, it's hard to come up with some
> reason to write something unique and different every time the
> document is published.

On the other hand it is really valuable to tell a reader 
exactly what is different, however minor and trite -- 
if the status has not changed, why publish 


> The more frequently the document is published,
> the more this is true.

Certainly not a good idea to idea to punish frequent 
publication.

> 
> Also, nobody really reads the status section because it's full of
> boilerplate junk. So there's little incentive for the editor to
> spend much time on it.
> 
> I recommend to remove the uniqueness requirement. It was, afaict,
> intended to force the status section to say something relevant
> and informative, but isn't a reasonable requirement given
>  - we have tons of boilerplate
>  - we would like to encourage frequent publication,
>    and things like an up date to "fix typos" should not require
>    a change of status text for the same of changing status text
>  - enforcing uniqueness when the goal is being informative and
>    relevant is rather sideways

"Fix typos" sounds good comment to me.
Tells me not to read it if I read the last one.
Really valuable comment.

In git[hub] the art of the commit comment is a subtle one.
Some people check in a big list of issues fixed in too much detail, some
people are too brief.

In github, the fact that you can see more than one version in the history fairly
easily means that it is OK to say "fix typos" for version n when version n-1
has a long comment about a major change.  (In gitgub you don't
typically say what you expect of your readers, like "please implement section 3
and help build tests for section 5" or "ignore this" or  "please check every typo"
but that is valuable)

So maybe if you publish often, then it would be best to include the changes
in each recent version as a SOTD.

It is frustrating how good people are at summarizing what's up with the document
in an elevator, but how hard it is to define the art!

timbl


> 
> ~fantasai
> 
>

Received on Thursday, 31 October 2013 10:31:26 UTC