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

Re: Editor's notes

From: Michael Cooper <cooper@w3.org>
Date: Thu, 23 Feb 2017 09:50:20 -0500
To: fantasai <fantasai.lists@inkedblade.net>, spec-prod@w3.org
Message-ID: <0bd36d6f-b4b3-faa9-c64c-644d29912ee0@w3.org>
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.

This thread essentially started with an observation that there are three 
types of notes and two styles for them, with notes and ednotes 
essentially sharing similar style. The thread started with a proposal to 
combine two types of notes - first notes and ednotes, later ednotes and 
issues. Several people have said they use all three concepts and want to 
retain them, but nobody has opposed separating the two styles into 
three. So all that is needed is a different style for ednotes. I don't 
care much about the specifics, I'm not a designer, as long as it's easy 
to tell apart from the other two, and from other styling features. If 
orange is already taken, maybe yellow, or a dashed border, or whatever 
fits into the overall design and communicates the distinction for those 
who use it.

> ~fantasai
Received on Thursday, 23 February 2017 14:50:29 UTC

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