W3C home > Mailing lists > Public > spec-prod@w3.org > January to March 2017

Re: Editor's notes

From: fantasai <fantasai.lists@inkedblade.net>
Date: Thu, 23 Feb 2017 15:06:15 -0500
To: Michael Cooper <cooper@w3.org>, spec-prod@w3.org
Message-ID: <d6371726-6dd7-aa4a-3118-a5c30615f3fd@inkedblade.net>
On 02/23/2017 09:50 AM, Michael Cooper wrote:
> On 2/22/2017 11:38 PM, fantasai wrote:
>> On 02/22/2017 02:27 PM, Michael Cooper wrote:
>>> On 2/22/2017 2:12 PM, fantasai wrote:
>>>> So, here's a question: is there a reason why ednotes should not use .issue styling?
>>>>
>>>> (Because, as I mentioned, the CSSWG has been getting along fine with using .issue for this class of usage.)
>>> I think several people in the thread have said they understand notes, ednotes, and issues to each have distinct semantics from
>>> each other. While not all groups use all those semantics, some do and we should preserve the feature. So I don't think ednotes
>>> should have issue styling. I'd just suggest orange to use the familiar traffic light metaphor, of notes being green meaning
>>> you don't need to worry much, issues being red meaning you should look out, and ednotes being orange or yellow meaning
>>> something in between. And of course, preserve the distinct "Editorial Note" title when put in by tools. Michael
>>
>> Orange is already used for advisements.
>>
>> You also didn't directly answer the question, so let me put some more background and you can try again.
>>
>> There is clearly a distinction between regular notes (which are intended for users of the spec and are expected to appear in
>> its final production) and ednotes (which are intended as an editor's note to himself or his partners). These are not
>> currently, but should probably, be distinctly styled.
>>
>> However, the only distinction brought up between an “issue” and an “ednote“ is that the ednote is not filed in GitHub, and
>> originates from the editor himself. If it were filed by someone else (e.g. If *I* read your spec and was like “This seems to
>> be missing an introduction” or “This section is confusing and should be rewritten”), it would be in GitHub.
>>
>> Firstly, I don't think distinguishing the originator of a spec issue is a matter for the spec styles to concern themselves
>> with.
>>
>> And secondly, if “it's filed in GitHub” vs “it's a concern that's merely inlined into the spec” is a distinction to be made,
>> it is already self-evident by the GitHub linking, or lack thereof.
>>
>> So again, is there a utilitarian reason why ednotes should not use .issue styling?
>
> I wouldn't characterize the difference, or lack of difference, between ednotes and issues in that way, that one is backed up
> by formal issues and the other isn't but in some views should be. Perhaps it's subjective exactly how ednotes and issues
> differ, but they do call different kinds of attention. My own best explanation is that "issues" are for technical issues with
> what the spec says and "ednotes" are for editorial issues with how the spec says it. That's just my own practice and
> perception, but it's clear that there are also other editors who spoke up in this thread and see value in using both issues
> and ednotes for different purposes that make sense to them. I get that in your editorial practices you don't make a
> distinction, but since others do, and have been using this distinction so for a long time, we shouldn't have tooling or
> styling take it away from us. That would actually lead to style forking as we'd have to use custom styles in each spec to
> restore the feature.

If the base styles are to support a distinction it needs
   a) widespread use
   b) unambiguous semantic distinction (for consistent application)
   c) a need for distinct styling (because the reader, for some reason, cares)

You've only made an argument for a).

~fantasai
Received on Thursday, 23 February 2017 20:06:52 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:22 UTC