Nomenclature heirarchy

• Mar 31, 2016 - 21:59

I am looking at possibly revising the pages in the Handbook concerning the palettes, and a basic problem has surfaced that needs to be addressed before I start any sort of re-write.

In technical writing, especially in collaborative efforts, the nomenclature used and its heirarchy must be firmly established, and once that is done, it must be adhered to by all the contributors or the whole project risks splintering and readers of one section will have difficulty relating the terminology in it with that in another section.

I am hesitant to attempt a major revision of the various pages on palettes and workspaces before settling this question. At the moment, I see confusion the heirarchy of the terms used, and would like the input of other members of the MuseScore community to see if a standard usage can be defined.

For example, here is one possible heirarchy for what appears to fall under the global description of Palettes:

WORKSPACES

Palettes

Master Palette (z)

Sub-palettes / Categories

Elements

Main Palette (F9)

Sub-palettes / Categories

Elements

Custom Palettes

Sub-palettes / Categories

Elements

There are a number of problems with this heirarchy, as well as with the nomenclature in it. For instance, a 'workspace' is currently defined in the Handbook as 'a collection of palettes'. According to the heirarchy above, that definition fails to clarify the distinction between a palette (z, F9, or custom) and a sub-palette or category (Clefs, Time Signatures, Accidentals, etc.). Should the Master and Main palettes be treated as separate entities (as shown above), and if they are, are the sub-categories of each identical and if so, why should we treat them separately?

It's complicated, as The Doctor is fond of saying. ;o)

Marc Sabatella is the primary resource for the content of the Handbook; I would really appreciate his input on this question before I stick my fingers in the pie.

Comments

• Mar 31, 2016 - 22:15

I'm happy to comment, but I'd like to clarify a statement - I don't think it is proper to think of me as the primary anything with regard to the Handbook. I've done very little with it, just written a couple of sections for features I implemented, teeaked a few things here and there.

Anyhow, your hierarchy doesn't quite fit with my impression of how things are organized, but maybe you are right and I'm wrong. Is the Master Palette really part of a workspace? I didn't think so, but maybe it is? I thought it was just the Main Palette - which *includes* any custom palettes you add. So the custom palettes are just specific sub-palettes of the main palette as far as I know, not a whole separate category of palette.

Reply

• Mar 31, 2016 - 23:11

Thanks for getting involved in this, and please don't denigrate your own contribution. Producing a coherent technical manual for anything more complex than a bottle-opener is WAY more difficult than most people realise, as anyone who's worked on one will confirm.

That particular heirarchy isn't 'mine', actually; I just threw that out there quickly to illustrate the problem we're facing. I agree with you that the Master Palette doesn't seem to be 'under' the Workspaces level, but according to the current text in the Handbook, it appears that it is. So...we have some work to do.

My present thoughts would separate workspaces and palettes conceptually as much as possible, and would probably create a new definition--'Palette Workspaces'--to cover the link between those two elements. In terms of heirarchy, any such new term would be 'below' the overall term 'Palette.' But that's the sort of thing I don't want to do without ensuring that it won't conflict with other pages in the Handbook. I want to make thing clearer, not more foggy. ;o)

Currently, I see things this way:

Palettes

>Master Palette ('z')
>>Categories (Grace Notes, Clefs, Key Signatures...) [Note: I would re-name this level and avoid the use of the terms 'palette' or 'sub-palette']
>>>Elements (individual symbols shown once the category is opened)
>>>>Limitations and options for using elements from the Master Palette

>Main Palette (F9)
>>Categories (Grace Notes, Clefs, Key Signatures...) [Note: I would re-name this level and avoid the use of the terms 'palette' or 'sub-palette']
>>>Elements (individual symbols shown once the category is opened)

>Custom Palettes
>>Definition and utility
>>How to create
>>>Workspaces, and creating a custom 'Palette Workspace'
>>How to add elements to a custom palette
>>Limitations and options for using elements from a custom palette

>Classes of objects in palettes
>>Active elements--Definition
>>>Use and insertion
>>Graphic 'image objects'--Definition
>>>Use and insertion

How does that look for a start?

Reply

• Mar 31, 2016 - 23:15

Again, "Custom palette" is not at the same level of hierarchy as "main palette". If it helps to think of this way: there is no such thing as a "custom palette" using your terminology. Only "custom categories", which includes both new categories (within the main palette) you create yourself and also customzied versions of existing categories.

But I don't like the term "category" here. It's a palette, even if it happens to be "sub-palette" of a larger palette. We don't want to have to say, "to add a dynamic, go to the Dynamics category of the Main Palette". It is far simpler to just say, "go to the Dynamics palette".

Reply

• Apr 1, 2016 - 00:08

I agree; custom palettes are not at the same heirarchal level as the Main or Master palettes. I should have made that clearer somehow, perhaps by indenting that entire level another notch. My fourth-grade teacher, Mrs. Heinechen, would have smacked my knucks with ruler for that goof.;o)

As to the term 'category', I don't insist upon that particular word, but I do think we need something other than 'palette' to describe that level in the heirarchy. Rule One in this sort of stuff is to avoid using the same term to refer to two different things, as you know better than I from your experience as a programmer. I can only imagine the consequences of using the wrong tag for something in a line of code.

To be obnoxiously didactic about it, 'Main' palette should fall under 'Master' palette, but I think we can slide on that one since the adjectives are pretty clear. (OTOH, I hope we don't someday find ourselves obliged to distinguish between 'Master' palette and 'Global' palette. ;o) Anyway, maybe 'sub-palette' would be better than 'category' in this case.

Reply

• Mar 31, 2016 - 22:58

I've done a fair amount of work on the Handbook, including the palette-related documentation (I'm the one who made it a single page called "Palettes and Workspaces" out of two separate pages). I understand it like this:

Palettes (F9)

Single noun referring to the widget docked on the left

Workspace

A set of palettes (see below) displayed in the Palettes widget (see above); two default workspaces, plus custom workspaces

Palette

Each expandable section is a palette; a custom palette can be part of a custom workspace

Element

Each icon displayed under a palette represents an element (generic term for pretty much anything that can exist in a score)

Master Palette (Shift+F9)

The big window with everything

Section

Each thing you can click on in the Master Palette's sidebar; also, what fills the window after clicking something in the sidebar

Symbols (Z)

A specific section of the Master Palette, containing limitless music-related graphics

Element

Same as above, among Symbols or any other section of the Master Palette

Reply

• Mar 31, 2016 - 23:16

Thanks for chiming in, Zack, and please excuse me if I didn't look up the names of the people who had previously worked on this section. I got involved due to a series of misconceptions I arrived at while trying to answer a new user's questions about graphic control of palette items.

I have just posted a lengthy reply to Marc on this subject (see above), which includes my current thinking about how to re-organise this page. Any comments or criticisms you may have on that post will be most welcome.

Reply

• Mar 31, 2016 - 23:40

I just realized something: you're using MuseScore 2.0.1, aren't you? That would cause you some extra confusion, because of this: #53331: View -> Palette needs be corrected to View -> Palettes The whole thing is definitely not one palette, "Main" or otherwise, but "Palettes" (look at its title bar even in your old version), and it contains multiple individual palettes—not "sub-palettes" or "categories," just palettes.

Reply

• Apr 1, 2016 - 00:16

Yes, I'm still using 2.0.1 (because I'm still working on scores for publication which were created using that version), but I am not referring to the right-click text from that version in considering this revision. I am working strictly from what is currently in the Handbook, with a view to making it clearer for all users. I don't suppose that the version of MuseScore I have installed has any incidence on which version of the Handbook appears when I call it using IE11? That would be too, too Google-esque....

Reply

• Apr 1, 2016 - 00:27

I was thinking that could explain where this "Main Palette" idea is coming from: you want to rename the "Palette" to the "Main Palette," and if that entire dockable widget is the "Palette," how can any one of its sub-divisions also be a "palette"?

But the whole thing is not the "Palette," it's the "Palettes." So don't make it into "Main Palette." It's just "Palettes," and individual palettes going together make up "Palettes."

See also the image I posted above, identifying a palette among palettes. It's not that complicated.

Reply

• Apr 1, 2016 - 01:30

Actually, it is that complicated. We need to look at this from the point of view of someone who knows little if anything about the program, not from the point of view that experienced users have developed over a period of months or years. That is the essence of good technical writing. If the user knew how to start that chainsaw, he wouldn't even bother to read the owner's manual. But if he doesn't, he needs to be told clearly that there is a difference between the choke and the throttle, even though they both control the flow of fuel to the carburetor. Otherwise, he'll flood the damned thing, pull his left arm off, and curse the idiot who wrote the manual.

If there is something distinct called the 'Master Palette' which is accessible via a different shortcut or menu operation, then the 'Palette' that comes up when one types F9 or clicks on View>Palette needs a distinct name. These two 'palettes' are distinct entities; they need to be described in distinct terms, or the users/Handbook readers won't be able to differentiate between them.

I have provisionally adopted the term 'Main Palette' to refer to what shows up when one types F9. MuseScore itself designates the palette that shows up in response to typing 'z' as the 'Master Palette'.

If you have a better suggestion to name the 'F9' palette (other than just plain 'Palette', which is not, in my view, sufficient), I'll be glad to hear it.

Reply

• Apr 1, 2016 - 19:56

Hmm. 2.0.1 does entitle the F9 sidebar 'Palettes plural, but it is refered to in the drop-down from the View menu as 'Palette' (singular). And the 'Master Palette' is singular both in the View drop-down and in its own title-bar. Don't know if any of that was changed for subsequent revisions, but you can check for me, if you don't mind. Since the Master and the F9 both have the same structure, the numerical case of the nouns in those title bars and the drop-down menus ought to match, one way or the other.

We definitely want the heirarchy of terminology in the Handbook to reflect the operational reality, but right now there are inconsistencies so we'll have to make some choices. We can look at modifying those titles in the program itself for a future release, but any revision of the current Handbook page will have to be based on 2.0.x for now.

Here's another aspect of the problem: Assuming that we describe the F9 sidebar as 'Palettes' (plural) in the documentation (and drop the 'sub-palette' or 'category' idea for now), we have current documentation which describes a 'workspace' as a collection of palettes. Quoting from the present version of the page:

A palette is a storage space containing a group of related musical symbols. A collection of palettes is called a workspace....

On that basis, typing F9 or 'z' brings up a workspace...but there is no checkbox in the 'View' drop-down called 'Workspace' and what comes up using either method is entitled 'Palettes'. I don't see any way to resolve this without moving 'workspace' to a different level in the heirarchy--or even taking it laterally right out of the Palettes heirarchy--and re-defining it.

I am familiar with the term 'workspace' from my use of ACAD, but it's not a concept that most people can grasp without help. What would you think of something like this:

A workspace is a sub-division of a larger collection of entities, which enables users to display the group of elements most appropriate for their work. MuseScore provides a number of workspaces by default (most often selected from a drop-down menu in a dialogue), and also enables users to create custom workspaces within which the user has control of which elements appear.

BTW, can you provide me with the distinction between 'elements' and 'entities' (if there is one)?

Reply

• Apr 1, 2016 - 20:07

A workspace is a collection of palettes that can be loaded into the Palettes window. This does not seem a particularly complex concept to me?

Pressing F9 brings up that Palettes window (if for some reason you have closed it). The contents of the Palettes window are defined by the current workspace. That seems simple and straightforward enough as well.

Pressing "Z" brings up the Master Palette window, which indeed contains multiple palettes just as the main Palettes window does, but has absolutely nothing to do with any worksapce as far as I know. Even though this window contains multiple palettes, calling the window "Master Palettes" doesn't really make sense to me - it feels grammatically awkward. I think simply calling it the "Master Palette" is better, and seems unlikely to actually cause confusion.

I am not sure what distinction you are making between "element" and "entity". The little squares within a palette are properly called "cells", the *contents* of those cells are probably best called "elements" although we also use the term "icons".

Reply

Do you still have an unanswered question? Please log in first to post your question.