Documentation Updates #1061
Documentation Updates #1061
Conversation
contribute/en/Style-and-Tone.md
Outdated
|
|
||
| “Fader” The UI that controls a channel. “Each fader has a mute button”, “The person’s fader” ,“Group faders together” (not “The person’s channel” or “Mute a Fader”, not “Slider” or “Volume control”) | ||
| “Fader” The UI used to control a channel. Not “slider” or “volume control”. Use when "channel" may not be appropriate, and preferebly only to refer to what a user sees on their screen. “Each fader has a mute button”, "leftmost fader". Remember: keep the user's view in mind when referring to the UI. For example, the visual effect of controlling a group of channels is to "make all the faders move together". But note that "fader" should **not** be used if "channel" would be a more accurate term. So, "reduce the channel volume" not "lower the fader". "Mute the channel" not "mute the fader". This is to disambiguate in cases where the UI isn't relevant, and help educate the reader in terms of the way things actually work. |
There was a problem hiding this comment.
The UI used to control a channel.
No:
"Fader": The UI control used to adjust the volume for a channel in the mix. Not “slider” or “volume control”.
(The fader is a slider widget. It does control volume. But as noted, use "Fader" when you're talking about the UI control for that purpose. "Slider" alone isn't good enough - far too vague. "Volume control" isn't good enough -- there are other ways to control the volume.)
Use when "channel" may not be appropriate,
No - it's not a synonym for "channel" in any way. It only refers to the UI control that's used to adjust volume in the mix. Nothing else.
“Each fader has a mute button”
That's wrong. A fader isn't a button, it's a fader (which is a slider). It can't be or have a mute button (and it's actually a mute checkbox - anyone looking for a mute button will be disappointed (although a checkbox is a specialised button, of course...)).
"leftmost fader"
That's okay.
the visual effect of controlling a group of channels is to "make all the faders move together"
Not necessarily. Not unless you move one of the faders. If you hit the solo or mute controls, the faders don't get affected.
But note that "fader" should not be used if "channel" would be a more accurate term.
And "fader" is only ever accurate when referring to the UI control that adjusts the channel volume in the mix.
There was a problem hiding this comment.
"Slider" alone isn't good enough - far too vague. "Volume control" isn't good enough -- there are other ways to control the volume.)
That's what I mean by "Not “slider” or “volume control.”" (that is, do not use those terms). It may be a bit elliptical, but this is the Style Guide.
it's not a synonym for "channel" in any way. It only refers to the UI control that's used to adjust volume in the mix. Nothing else.
Yes, but the point of the Guide is to help us make sure we know how to use "fader" and when to use "channel". They are not synonyms, but unless we are going to ban the term "fader" completely, we need some guidance on how to use it.
A fader isn't a button, it's a fader (which is a slider). It can't be or have a mute button
OK so choose a better example. The point here is to give some kind of guidance on possible usage. But if somebody needed to refer to the mute button's location, they might need to refer to it in relation to the fader.
This isn't an exact science :-) And it's not the technical doc for what these things are, it's for writers who may need guidance in unknown contexts. No problem with better examples though.
There was a problem hiding this comment.
"Fader" - the UI control that adjusts the channel volume heard in the mix. It should not be called "volume slider" or "volume control", just "fader" (adding the context of the mixer, if needed).
How's that? It doesn't need to talk about anything else. It's confusing to talk about anything else. All it should talk about is the volume in the mix.
There was a problem hiding this comment.
Sorry, not sure what you're quoting there.
There was a problem hiding this comment.
Sorry, not sure what you're quoting there.
Where?
There was a problem hiding this comment.
No, saying "group the channels" and "mute the channel" is correct. "Fader" and "Channel" are absolutely not interchangeable.
"Fader" only refers to the adjustment of the channel volume:
- "Use the fader to adjust the channel volume level" would be acceptable -- it explains what the fader UI control does.
- "Use the group checkbox to put channels into a group which you can then adjust further together" would be acceptable -- it explains what group UI control does.
- etc
There was a problem hiding this comment.
Yes, I know :-) I just wanted to be clear about the decision we're making here, but I'm obviously not explaining myself well enough.
To illustrate - the following hypothetical text is technically correct when describing the UI to someone looking at the Jamulus mixer panel without any other knowledge of how Jamulus works:
"You can adjust the volume of a channel with the fader, and mute or solo that channel using the button under the fader. You can also group the channels together, and when you move one of the faders in that group, the other faders in that group move with it."
The following is not technically correct, but just as informative from a naive reader's POV:
"You can adjust the volume of a channel with the fader, and mute or solo that channel using the button under it. You can also group faders together, and when you move one of the faders in that group, the other faders in that group move with it."
The way style guides usually work is to mandate one term for what the user sees on the screen. But we don't want to do that because we want to stay true to the underlying technical definitions as that might head off problems later on. And fair enough - just as long as we know we are making that decision when the reader may well logically, if in error, conclude that the terms "fader" and "channel" are interchangeable, and wonder why we appear inconsistent. This is why I was wanting to add that we do this to help "educate the reader".
There was a problem hiding this comment.
Yes - and the reason
You can also group faders together,
is not helpful is that you can also mute and solo groups, I think, so it misleads the reader into thinking that it does not apply to mute and solo controls.
There was a problem hiding this comment.
Exactly so - although it's not relevant to my point about the style guide :-) But no matter. In the interests of merging this, I won't labour that any more.
There was a problem hiding this comment.
It's relevant to authors to know why a direction is being given.
| @@ -83,17 +83,19 @@ Refer to UI labels in inverted commas (eg 'click on the “mute” button') | |||
|
|
|||
| Jamulus is “Free and Open Source (FOSS)” (not “free software” or “open source”) | |||
|
|
|||
| “Channel” The audio signal as part of a mix. “Mute a channel”, “Maximum number of channels”, “Group channels together” (not “Mute a person” because one person might be using multiple channels). | |||
| “Channel” The audio signal as part of a mix. “Mute a channel”, “Maximum number of channels”, “Group channels together”. | |||
There was a problem hiding this comment.
I call these connections. Each connection has one or two channels (mono or stereo). That's the language of the JSON-RPC API. I haven't studied the debate, above, but try to avoid using one word to mean two different things as we do here.
There was a problem hiding this comment.
My view is based on the code. For me, in Jamulus terms "Channel" refers to what CChannel does - wraps a socket and exchanges data with another Jamulus instance. That includes both audio and control data. The style guide, however, isn't for code developers. It's for people documenting Jamulus, so that such documentation is consistent.
Where some context - such as MIDI - makes the normal usage of Channel (with a capital letter - I think we should specify that) unclear, then the author needs to make it plain, as appropriate.
I'm not sure the JSON-RPC documentation - as the feature has been considered experimental - has been subject to the Style Guide.
There was a problem hiding this comment.
I'm not sure the JSON-RPC documentation - as the feature has been considered experimental - has been subject to the Style Guide.
Currently it is, but I'd like to get it more mainstream in Jamulus 4. So we should be consistent there too.
|
|
||
| “Person” A human connected to a server (may be on multiple channels). We might say "People on the server", or "People who have muted themselves", rather than _Musicians_ or _Channels_. | ||
| “Person” When "channel" or "fader" isn't a good term (according to the above definitions), we refer to "people" connected to a server rather than "musicians" since (in English) the latter term does not imply singers. |
There was a problem hiding this comment.
This is "ok" but quite broad. "Person" should always refer to the actual human being. A Person may have multiple channels etc.
There was a problem hiding this comment.
I've settled on musician but person is ok. The reality is that it might be a bot, and so connection is accurate, but being understood is more important in user docs than being accurate. This idea that singers aren't musicians is nothing I've heard of.
There was a problem hiding this comment.
This idea that singers aren't musicians is nothing I've heard of
Me neither, but I'm not a native speaker.
There was a problem hiding this comment.
I've settled on musician but person is ok. The reality is that it might be a bot, and so connection is accurate, but being understood is more important in user docs than being accurate. This idea that singers aren't musicians is nothing I've heard of.
That would be news to The Guild :-) But in our case it's to help in the translation of other languages, and also because you can have listeners and others in some contexts perhaps.
And yes, being understood is more important than accuracy here. The docs are the spec, the style guide is there to establish consistency and clarity of the docs, where possible.
There was a problem hiding this comment.
This is "ok" but quite broad. "Person" should always refer to the actual human being. A Person may have multiple channels etc.
Yes. This is why it says "When "channel" or "fader" isn't a good term"
There was a problem hiding this comment.
The reality is that it might be a bot, and so connection is accurate, but being understood is more important in user docs than being accurate.
No, "Person" refers to a real human. A bot might also have a connection but that's not what a Person refers to. There can be more than one person on a single connection, too, so we have to be clear that "Person" is not the same thing as "connection".
When we're talking about what you're using "connection" for, the Style Guide should be advising "Channel".
Various updates to documentation.
Does this need translation?
NO (because keeping this branch to stuff we don't translate)
Checklist