Editor's notes

[Marcos Caceres]

Hi Spec Editors,

Some specs feature "editors notes", which are notes that an editor
leaves for the reader or for themselves for whatever reason. These
editors notes are styled in the same way as regular notes (green box,
with a bold "heading").

We are wondering, should such editors notes be stylistically
distinguished from regular spec notes (and, should they be included at
all in specs)?

If the answer is "yes, they should be styled differently": then we
should decide on how to distinguish them in "base.css" (see [1]).

If the answer is "no, just keep them the same", then ReSpec will
automagically start to convert them to "notes" (by changing the css
class value to from "ednote" to "note").  If I don't hear any
responses, I'll assume "no" and change ReSpec to match.

Kind regards,
Marcos

[1] https://github.com/w3c/tr-design/issues/110

[Michael Cooper]

For me keeping the concept of editors' notes separate from regular notes
is important.

Regular notes are interpretive guidance about the spec features.

Editors' notes are statements about the production of the spec, such as
"this is incomplete", "we really want input on this", etc. My practice
is to remove editors' notes by Rec (and don't mind if Pubrules wants to
enforce that), and I make sure they're pretty minimal from CR on, but in
Working Draft I use them a lot.

I'm agnostic about the style, for me the different note header is enough
but see value in a greater style differentiation. I would not want to
lose the feature from Respec.

Michael

Post by Marcos Caceres
Hi Spec Editors,
Some specs feature "editors notes", which are notes that an editor
leaves for the reader or for themselves for whatever reason. These
editors notes are styled in the same way as regular notes (green box,
with a bold "heading").
We are wondering, should such editors notes be stylistically
distinguished from regular spec notes (and, should they be included at
all in specs)?
If the answer is "yes, they should be styled differently": then we
should decide on how to distinguish them in "base.css" (see [1]).
If the answer is "no, just keep them the same", then ReSpec will
automagically start to convert them to "notes" (by changing the css
class value to from "ednote" to "note"). If I don't hear any
responses, I'll assume "no" and change ReSpec to match.
Kind regards,
Marcos
[1] https://github.com/w3c/tr-design/issues/110

[fantasai]

For me keeping the concept of editors' notes separate from regular notes is important.
Regular notes are interpretive guidance about the spec features.
Editors' notes are statements about the production of the spec, such as "this is incomplete", "we really want input on this",
etc. My practice is to remove editors' notes by Rec (and don't mind if Pubrules wants to enforce that), and I make sure
they're pretty minimal from CR on, but in Working Draft I use them a lot.
I'm agnostic about the style, for me the different note header is enough but see value in a greater style differentiation. I
would not want to lose the feature from Respec.

The CSSWG uses class="issue" for such notes. So the question is, is there a three-way distinction in regular use (note vs.
ednote vs. issue) or just a two-way distinction (note vs. issue).

~fantasai

[Shane McCarron]

There is definitely a 3 way disctinction. ReSpec, in particular, can
inject information about "issues" and tie them into github issue
discussions. These are distinct from "notes" (non-normative advice to the
reader / implementor) and "ednotes" (information the editor wants to
capture and bring to the attention of a reviewer for future action).

Post by fantasai

For me keeping the concept of editors' notes separate from regular notes is important.
Regular notes are interpretive guidance about the spec features.
Editors' notes are statements about the production of the spec, such as
"this is incomplete", "we really want input on this",
etc. My practice is to remove editors' notes by Rec (and don't mind if
Pubrules wants to enforce that), and I make sure
they're pretty minimal from CR on, but in Working Draft I use them a lot.
I'm agnostic about the style, for me the different note header is enough
but see value in a greater style differentiation. I
would not want to lose the feature from Respec.

The CSSWG uses class="issue" for such notes. So the question is, is there
a three-way distinction in regular use (note vs. ednote vs. issue) or just
a two-way distinction (note vs. issue).
~fantasai

[Tab Atkins Jr.]

There is definitely a 3 way disctinction. ReSpec, in particular, can inject
information about "issues" and tie them into github issue discussions.
These are distinct from "notes" (non-normative advice to the reader /
implementor) and "ednotes" (information the editor wants to capture and
bring to the attention of a reviewer for future action).

Note that Bikeshed can do this too; you just tag the issue with the
Github issue number. It still classifies everything that's a problem
to be resolved as an "issue", and styles them accordingly; I think
that's arguably the right thing to do.

"Note" styling (green background) should be reserved for actual spec
notes - additional info that is helpful to the reader of the spec.

~TJ

[Marcos Caceres]

Post by Tab Atkins Jr.

There is definitely a 3 way disctinction. ReSpec, in particular, can inject
information about "issues" and tie them into github issue discussions.
These are distinct from "notes" (non-normative advice to the reader /
implementor) and "ednotes" (information the editor wants to capture and
bring to the attention of a reviewer for future action).

Note that Bikeshed can do this too; you just tag the issue with the
Github issue number.

Shameless plug, but works the same in ReSpec [1].

Post by Tab Atkins Jr.
It still classifies everything that's a problem
to be resolved as an "issue", and styles them accordingly; I think
that's arguably the right thing to do.
"Note" styling (green background) should be reserved for actual spec
notes - additional info that is helpful to the reader of the spec.

I tend to agree with the above: ednotes probably should not be green.

[1] https://github.com/w3c/respec/wiki/Referencing-GitHub-issues-in-your-spec

[fantasai]

Post by Marcos Caceres

Post by Tab Atkins Jr.

There is definitely a 3 way disctinction. ReSpec, in particular, can inject
information about "issues" and tie them into github issue discussions.
These are distinct from "notes" (non-normative advice to the reader /
implementor) and "ednotes" (information the editor wants to capture and
bring to the attention of a reviewer for future action).

Note that Bikeshed can do this too; you just tag the issue with the
Github issue number.

Shameless plug, but works the same in ReSpec [1].

Post by Tab Atkins Jr.
It still classifies everything that's a problem
to be resolved as an "issue", and styles them accordingly; I think
that's arguably the right thing to do.
"Note" styling (green background) should be reserved for actual spec
notes - additional info that is helpful to the reader of the spec.

I tend to agree with the above: ednotes probably should not be green.
[1] https://github.com/w3c/respec/wiki/Referencing-GitHub-issues-in-your-spec

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.)

~fantasai

[Michael Cooper]

Post by fantasai
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

[fantasai]

Post by fantasai
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?

~fantasai

[Michael Cooper]

Post by fantasai

Post by Michael Cooper

Post by fantasai
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.

Michael

Post by fantasai
~fantasai

[Tab Atkins Jr.]

Post by Michael Cooper
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.

No, fantasai and I both oppose splitting the two stylings into three.
fantasai explicitly argued against styling ednotes and issues
differently.

~TJ

[fantasai]

Post by fantasai

Post by fantasai
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

[Marcos Caceres]

On February 24, 2017 at 7:07:49 AM, fantasai

Post by fantasai
If the base styles are to support a distinction it needs
a) widespread use

We have evidence of this [1]. If you go through the specs there
(skipping the ones that just include "ednote" in the CSS), you will
see that it's indeed used quite a lot (~roughly around 30+ specs) -
and with a few declarations within each spec.

Post by fantasai
b) unambiguous semantic distinction (for consistent application)

This is a little vague (not what you are asking for - just that we
know ednotes sit between an issue and note.

Post by fantasai
c) a need for distinct styling (because the reader, for some reason, cares)

Right now, the only distinction from notes is that editor's notes get
the mast "EDITOR'S NOTE".

I was actually reviewing the Web Payment Request spec yesterday and
hit one in the Privacy and Security sections [2]. I encourage you to
take a look, because editor's notes can get used for pretty serious
things (and current styling making them look like notes can downplay
the significance - which is also why I tend to agree that ednotes are
"issues).

[1] https://github.com/search?l=HTML&q=org%3Aw3c+class%3Dednote&type=Code
[2] https://w3c.github.io/browser-payment-api/#security-considerations

[Shane McCarron]

Let's not forget that sometimes ednotes are NOT issues. They are things
like "Ed. Note: This section was moved from location X to location Y as per
the discussion at meeting Z." or "Ed. Note: It is possible that in the
future this section will be split out into a separate document for
maintenance purposes."

Post by Marcos Caceres
On February 24, 2017 at 7:07:49 AM, fantasai

Post by fantasai
If the base styles are to support a distinction it needs
a) widespread use

We have evidence of this [1]. If you go through the specs there
(skipping the ones that just include "ednote" in the CSS), you will
see that it's indeed used quite a lot (~roughly around 30+ specs) -
and with a few declarations within each spec.

Post by fantasai
b) unambiguous semantic distinction (for consistent application)

This is a little vague (not what you are asking for - just that we
know ednotes sit between an issue and note.

Post by fantasai
c) a need for distinct styling (because the reader, for some reason,

cares)
Right now, the only distinction from notes is that editor's notes get
the mast "EDITOR'S NOTE".
I was actually reviewing the Web Payment Request spec yesterday and
hit one in the Privacy and Security sections [2]. I encourage you to
take a look, because editor's notes can get used for pretty serious
things (and current styling making them look like notes can downplay
the significance - which is also why I tend to agree that ednotes are
"issues).
[1] https://github.com/search?l=HTML&q=org%3Aw3c+class%3Dednote&type=Code
[2] https://w3c.github.io/browser-payment-api/#security-considerations

[Florian Rivoal]

Let's not forget that sometimes ednotes are NOT issues. They are things like "Ed. Note: This section was moved from location X to location Y as per the discussion at meeting Z." or "Ed. Note: It is possible that in the future this section will be split out into a separate document for maintenance purposes."

I don't see how these aren't regular notes. Sure, they're written by the Editor, but given that the Editor is the one who writing the entire document, that's a bit tautological.

—Florian

[Shane McCarron]

A regular note is typically non normative content that remains in a spec
forever. Ed notes are more ephemeral and generally are ascot the document
and its development rather than advice about the normative content .

Post by Shane McCarron

Post by Shane McCarron
Let's not forget that sometimes ednotes are NOT issues. They are things

like "Ed. Note: This section was moved from location X to location Y as per
the discussion at meeting Z." or "Ed. Note: It is possible that in the
future this section will be split out into a separate document for
maintenance purposes."
I don't see how these aren't regular notes. Sure, they're written by the
Editor, but given that the Editor is the one who writing the entire
document, that's a bit tautological.
—Florian

[Tab Atkins Jr.]

Post by Shane McCarron
A regular note is typically non normative content that remains in a spec
forever. Ed notes are more ephemeral and generally are ascot the document
and its development rather than advice about the normative content .

For both of the examples given in your previous message, the CSSWG has
either used regular notes, or just source-document comments, and not
seen a problem.

All of this is supporting the argument that "ednote" doesn't have a
strong semantic concept, making it unclear precisely when to use it.
The existing note/issue dichotomy is very clear in comparison - info
vs problems. Source-document comments handle the final category of
"notes to future self / other editors, that aren't relevant to other
spec readers".

~TJ

[Gregg Kellogg]

In specs I work on (JSON-LD and others) ednote is used during development to communicate status between editors. Issues, at tied back to GitHub and cover more long-standing discussions about spec content that are usually not simple editorial points. Please keep ednote.

Gregg Kellogg
Sent from my iPhone

For me keeping the concept of editors' notes separate from regular notes is important.
Regular notes are interpretive guidance about the spec features.
Editors' notes are statements about the production of the spec, such as "this is incomplete", "we really want input on this",
etc. My practice is to remove editors' notes by Rec (and don't mind if Pubrules wants to enforce that), and I make sure
they're pretty minimal from CR on, but in Working Draft I use them a lot.
I'm agnostic about the style, for me the different note header is enough but see value in a greater style differentiation. I
would not want to lose the feature from Respec.

The CSSWG uses class="issue" for such notes. So the question is, is there a three-way distinction in regular use (note vs. ednote vs. issue) or just a two-way distinction (note vs. issue).
~fantasai

[Gregg Kellogg]

In specs I work on (JSON-LD and others) ednote is used during development to communicate status between editors. Issues, at tied back to GitHub and cover more long-standing discussions about spec content that are usually not simple editorial points. Please keep ednote.

Gregg Kellogg

Post by Marcos Caceres
Hi Spec Editors,
Some specs feature "editors notes", which are notes that an editor
leaves for the reader or for themselves for whatever reason. These
editors notes are styled in the same way as regular notes (green box,
with a bold "heading").
We are wondering, should such editors notes be stylistically
distinguished from regular spec notes (and, should they be included at
all in specs)?
If the answer is "yes, they should be styled differently": then we
should decide on how to distinguish them in "base.css" (see [1]).
If the answer is "no, just keep them the same", then ReSpec will
automagically start to convert them to "notes" (by changing the css
class value to from "ednote" to "note"). If I don't hear any
responses, I'll assume "no" and change ReSpec to match.
Kind regards,
Marcos
[1] https://github.com/w3c/tr-design/issues/110

[m***@marcosc.com]

Post by Gregg Kellogg
In specs I work on (JSON-LD and others) ednote is used during development to communicate status between editors. Issues, at tied back to GitHub and cover more long-standing discussions about spec content that are usually not simple editorial points. Please keep ednote.

Just to be clear, ednotes are not going away :) the question is if we, as a community, want to see them styled differently from regular notes.

Post by Gregg Kellogg
Gregg Kellogg

Post by Marcos Caceres
Hi Spec Editors,
Some specs feature "editors notes", which are notes that an editor
leaves for the reader or for themselves for whatever reason. These
editors notes are styled in the same way as regular notes (green box,
with a bold "heading").
We are wondering, should such editors notes be stylistically
distinguished from regular spec notes (and, should they be included at
all in specs)?
If the answer is "yes, they should be styled differently": then we
should decide on how to distinguish them in "base.css" (see [1]).
If the answer is "no, just keep them the same", then ReSpec will
automagically start to convert them to "notes" (by changing the css
class value to from "ednote" to "note"). If I don't hear any
responses, I'll assume "no" and change ReSpec to match.
Kind regards,
Marcos
[1] https://github.com/w3c/tr-design/issues/110

[Gregg Kellogg]

Post by m***@marcosc.com

Post by Gregg Kellogg
In specs I work on (JSON-LD and others) ednote is used during development to communicate status between editors. Issues, at tied back to GitHub and cover more long-standing discussions about spec content that are usually not simple editorial points. Please keep ednote.

Just to be clear, ednotes are not going away :) the question is if we, as a community, want to see them styled differently from regular notes.

Other than ensuring that it’s clear this is an Editor’s Note vs a regular note, I don’t really have an opinion. It might be worth having some logic to verify that all ednotes are removed before CR, or some other suitable milestone.

Gregg

Post by m***@marcosc.com

Post by Gregg Kellogg
Gregg Kellogg

Post by Marcos Caceres
Hi Spec Editors,
Some specs feature "editors notes", which are notes that an editor
leaves for the reader or for themselves for whatever reason. These
editors notes are styled in the same way as regular notes (green box,
with a bold "heading").
We are wondering, should such editors notes be stylistically
distinguished from regular spec notes (and, should they be included at
all in specs)?
If the answer is "yes, they should be styled differently": then we
should decide on how to distinguish them in "base.css" (see [1]).
If the answer is "no, just keep them the same", then ReSpec will
automagically start to convert them to "notes" (by changing the css
class value to from "ednote" to "note"). If I don't hear any
responses, I'll assume "no" and change ReSpec to match.
Kind regards,
Marcos
[1] https://github.com/w3c/tr-design/issues/110

[Marcos Caceres]

Post by Gregg Kellogg

Post by Gregg Kellogg
Other than ensuring that it’s clear this is an Editor’s Note

vs a regular note, I don’t really have an opinion. It might be worth
having some logic to verify that all ednotes are removed before
CR, or some other suitable milestone.

I can add this to ReSpec's linter. Should we say CR as the cut off? that is, if CR or greater, then generate warning (suggesting it be changed to a real "note", "issue", or removed).