3.0 Handbook

• Nov 2, 2018 - 16:23

With the expectation that the beta version will be released in the next month, it is really time to start working on the handbook, especially when it comes to new or radically changed features. Playing with version 3.0 I can learn a lot, but there are things that I have no idea what they do like the PDF transcribing assistant and the Score comparison tool. The item that made me start this thread was how the Hide When: in staff properties and Do not hide if system is empty are supposed to work. My understanding was that users could prevent instruments from being hidden in some systems but these items make no sense, like what is Instrument in the drop down.


Absolutely, we need to start working the Handbook soon. I want to help organize these efforts, but am not quite sure yet what this means. Given that there are probably still changes yet to come, it may be too early for final screenshots etc, but getting some interim documentation on the new features to aid people wanting to test 3.0 or work on the Handbook is indeed likely the first priority. So I'd say you can expect to see some things coming. Feel free to discuss further here.

Anyhow, to address your specific question about staff hiding:

The idea is that we want to provide more control over hiding of staves than was possible in 2.x. It used to be the case that turning on hide empty staves made all staves candidates for hiding, unless you marked then Never hide. So if you wanted most of the score to always show but only one staff to appear and disappear as needed, this was a lot of work - first set all other staves to "Never hide", then enable "Hide empty staves". Now with 3.0, you can leave "Hide empty staves" off and set just the one staff's "Hide when empty" property to "Always". That means that one staff will be hidden when empty regardless of the global "Hide empty staves" setting for the score. "Never" means the same thing that the 2.0 "Never hide" meant - it won't be hidden even if it is empty and hide empty staves are turned on. "Instrument" means it will be hidden only if all staves of that instrument are hidden - so you don't have cases where the top stafff of a piano part is visible but the bottom isn't. "Do not hide if system is empty" has not changed - the idea is that you can designate one or more staves to be the token staves to display on those systems that are completely empty, when "Hide empty staves" is enabled. Otherwise, you'd end up with some measure completely missing from your score.

None of this in itself is intended to give system-by-system control over which staves are hidden where, but it's another way of accomplishing the same basic thing for the common case where you have a score with N staves and you want N+! staves on just one system. Rather than say you want to hide empty staves on that system only, you can simply set that one temporary staff to "Hide when empty: always". Same end result, but without depending on the current system layout (which is the basic problem inherent in trying to make any properties dependent on a specific system).

However, I would note we now have a "staff type change" element (currently on the text palette, which I think is completely inappropriate since it is not text at all). If you add this to a measure in your score, you can then customize staff properties from that point forward via the Inspector. But only a few staff properties are exposed here, and "Hide when empty" isn't one of them. I suspect it is pretty simple to add to the list of available properties. Adding "Hide when empty" to the list would enable things like having an instrument show on all systems for one movement of a piece but be hidden when empty in another movement, etc. You could use this technique to show a different set of instruments for each movement, and yet have each movement always show the instruments relevant to that movement whether empty for a system or not. That's something I'd still hope to see added at some point.

In reply to by mike320

It's probably true that "Hide when empty: always" doesn't add any new capabilites, but certainly adds much to the ease. Adding a temporary staff to a score now requires but one operation rather potentially dozens. Did I somehow fail to make that clear? Try in 2.0 to have a score for 20 instruments that are always shown, but one instrument that appears and disappears where needed. Possible but painful in 2.0, trivially easy in 3.0. Whereas there is nothing that can do more easily in 2.0 than 3.0 - everything is either the same or easier.

I suspect there might be some arrangements of hidden / empty staves now possible that might not have been before, but no practical examples of this come to mind offhand.

In reply to by neGjodsbol

Indeed, the current 2.3.2 situation with respect to temporary staves is needlessly complex. That's why these improvements were made. The process will be much simpler 3.0, so actually the Handbook can now focus on how to accomplish simple tasks simply without the need to describe awkward workarounds. Should make the overall page simpler and more useful to people just wanting to get the job done.

Back to the real issue.
When is the right time to start in the handbook? Who will take the lead, and how will it be organized?

Same applies to localization.
I know we wont be able to have Handbook ready, but the translations in Transifex ought to be ready at time of release.

In reply to by neGjodsbol

The Handbook has always been a community effort, I expect that to remain the case, but it does require site support obviously, and then generally has fallen on Thomas. I expect I might take more of a leadership role on organizing things as part of my initiative to improve our overall online help story. I'd say we are in the initial stages of thinking about this, so the timing of this thread is perfect.

In reply to by Marc Sabatella

Since the handbook always has been a community effort with ongoing changes, I think starting to develop the handbook now, with the current or expected behavior explained so alpha, and very soon beta, testers will know how to use some of the new bells and whistles. When it gets closer to final release the handbook will be closer to being up-to-date when that time comes. I would expect that there would be discussions in this forum prior to changes in the way features function prior to making drastic changes.

In reply to by Marc Sabatella

My top priority right now is creating the sort of preliminary documentation that will needed now to produce better documentation later (as well as to hlep users directly in the mean time). This actually goes beyond just thinking about the Handbook but trying to look at the big picture.

So I am working on assembling a list of changes and tutorials for some of the biggest ones. The list of changes itself can be collaborative; I expect I'll manage to miss things in my own. I'll post more info shortly.

In reply to by Marc Sabatella

Whether we create preliminary descriptions to be used by the testers, and developers, or we start to write the handbook entries to-be, we will need a place to put these, so a separate site seems to be needed.
You should consider restricting acess to users who have registered for this, so that 'ordinary' users does not end up there by mistake.

In reply to by neGjodsbol

My assumption is that we will use a similar system to what we did for 2.0, with a totally separate copy of the Handbook for 3.0 here on this site, that anyone had permission to access it but there weren't prominent links to it so basically the only way to get there was if you knew about it.

In reply to by Marc Sabatella

One thing we migth look at, is the structure of the top pages.

Today we have two pages headed Handbook.

One is a hybrid between an introduction to the handbook, and a detailed TOC.

The other is a simple listing of the autogenerated Outline.

Instead I suggest that the top level is the Handbook page, which is always displayed by links to "Handbook".
It should contain
* a brief intro about the purpose of the handbook
* a link to other help ressources
* a note about "how you can help"
* a download link for the Pdf version
* the outline index of the handbook

The next level could start with
- Introduction to Handbook
- Detailed TOC
- Getting started
- Basics

In reply to by neGjodsbol

Actually, my hope is to have a local version of the Handbook included with the program, ideally updated on the fly via the Resource Manager like translations and extensions. Although I am not sure if PDF or HTML makes more sense for this purpose. I guess it wouldn't hurt to include both. Anyhow, if a PDF version is included with the program, the need to make it prominently visible for download goes away.

In reply to by Jojo-Schmitz

Why would you prefer a single page HTML? To me it's much less desirable than separate "pages" as per the usual way HTML and the Handbook in particular is organized. Behavior of Back button is less precise, the scroll bars become fiddly on pages that long, "Home" and "End" keys become disastrous, printing is more awkward, etc.

In reply to by mike320

One page because it'd be way less stuff to manage, just that one single link to download.
PDF is just one page too, with the same effects to Home/End, etc.

...it took forever to display the HTML page on my computer.
Because it get generated on the fly on the server (and so up-to-date to the minute, not just generated once a day like the PDF). Once done and stored locally it loads in no time

In reply to by Jojo-Schmitz

The Resource Manager seems perfectly capable of downloading packages of files for extensions, I can't see any reason it would struggle if those happened to be HTML files as opposed to SFZ, XML, etc. And yes, I would lean toward multiple HTML over a single PDF if we were to provide only one option, because it's easier to work with in most ways, but providing the PDF as well wouldn't hurt.

In reply to by neGjodsbol

Could you explain what pitfalls you anticipate? The resource manager seems to be a well-tested facility that works very well with very few problems reported.

Good question on language, though. I guess we would by default include the version of the handbook that goes with the current translation. In fact, maybe it makes sense to just package it that way? If not, then just offer the choice as we do know. Definitely open to suggestions.

In reply to by Marc Sabatella

Should maybe have said surprises, as I have nothing specific.
I merely wanted to stress the need for testing.
Afterall you are suggesting that we can move a large and complex on-line handbook from the server environment to a local PC environment (actually several different). Even though the tools may be there I dont see this as a trivial process.

In reply to by neGjodsbol

Understood, and of course testing will be needed. But FWIW, while the Handbook might seem like a large and complex thing, in the end there is really nothing to it but a collection of HTML files - I think they are all even in the same folder. The *source" is not HTML - it's markup in the sites own format - but somewhere the work of generating HTML files with correct site- and language-relative links is already being done.

Anyhow, if for whatever reason it doesn't happen for the initial 3.0 release, it's always something that could be added on an update. Heck, if the program updates really are as regular as it has been suggested they might be, maybe it's not even worth the trouble of making the Handbook dynamically updatable - just include the HTML and PDF files with the application itself and be done with it.

In reply to by neGjodsbol

At some point, sure. I'm trying to focus on the big picture. But really, no reason it couldn't be both. Either as two separate menu items, or one menu item that opened the main local HTML page, which could itself have a link to the PDF. These are very small implementation details to be considered when the time comes.

In reply to by Jojo-Schmitz

I haven't seen problems with that fallback in the current handbook, but I do see a problem when the english version is updated, as there is no way to ensure that translations are updated.
It might be possible to extract the most recent page, when creating the local version, but I'm not sure how this can be handled in the on-line version.

In reply to by neGjodsbol

Perhaps when the English page is edited it can automatically set the checkbox that the current page is out of date in other languages. Perhaps translators could then subscribe to changes in their selected translation(s) so they know when they may need to update the translation. I see this as a similar idea to subscribing to forum posts. The local handbook could then be updated with the other language updates or at least using the resource manager in the help menu.

In reply to by Jojo-Schmitz

@Jojo, what you say is true, but there is currently no good way to notify translators of changes in the handbook. Every change to the English handbook does not require an update to other languages' translations, but at least the knowledge that a change occurred will help the translators know that an update may be needed.

Perhaps the e-mail notification could even include a comparison of revisions from the latest update to the previous like:

handbook update.PNG

This one would of course be ignored by most translators. BTW, this just happens to be the last update to the landing page for the handbook.

In reply to by Marc Sabatella

Besides the technical and process discussion, we also need to look at content.
Here are some points for discussion:

Remove the "Getting started" chapter
The section on installation could be better placed in the download page. Once you have installed MS you dont need it anymore.
'Creating your first score' is handled better in the videos and tutorials.
Updates have become automated, so that section could dropped or moved to appendix.

Reorganise the start page
First step should be to move the TOC to a seperate page, so the top page can be focused on directing the user to the right section.
Then divide intro a few major categories, and provide a brief intro to each.
Selecting a category will drill down to a specific page for that category.
Categories could reflect the things we can do with MS.
* Entering a score
* Presentation
* Play
* Import/Exportere
* Customization
I think advanced topics should go intro the categories.
Guides on user participation, forums, bug reporting might go into the new 'Get help' facility.
Release notes ciold be kept, but should go into the appendix.

One thing I'd like to see, if it can be maintained, is and alphabethical index.
Also the Glossary could do vwith a bit more attention.

Hi everyone, thanks for kicking off the handbook 3 task. The plan as it stands is to follow the same strategy as with handbook 2.

Preparations on the server side

  1. Make a copy of book 2 to book 3 for the English locale only. So none of the translations will be copied over.
  2. Mark those copied pages as work in progress, and therefore, exclude them from the translation flow for now.
  3. We will try to automatically change all the links in the copied pages, so this won't have to be done by hand, but not sure we will manage yet.
  4. Editing of musescore 3 handbook can start, but musescore 2 handbook remains available for editing as well, and the PDF is still only created for handbook 2 for now.

Community work

  1. Create new top handbook page, possibly just copy over the content of the existing handbook 2 page.
  2. Edit existing and add new child pages to musescore 3 handbook
  3. Change the outline if needed but normally this should only apply for new pages
  4. Suppose the book is ready before release, we can consider opening up the book 3 for translation

Final server side work

  1. Switch PDF generator from musescore 2 book go musescore 3 book
  2. Close the musescore 2 handbook pages for editing and add notice with a link to the new handbook 3 page, just as we link from the musescore 1 handbook page to musescore 2 page.
  3. Switch the pretty urls from musescore 2 handbook pages to musescore 3 pages.
  4. Index musescore 3 handbook pages in the search index and exclude the handbook 2 pages from search.

I will soon let you know when the initial server side work will be done. Meanwhile don't hesitate to give feedback.

In reply to by Thomas

_ consider opening up the book 3 for translation_ I'd like to see the entire structure to be "copied" to the national versions, with automatically falling back to the English page when a translation of a particular page is not yet available. That way every language's version is always complete, even if not completely translated. Better an English page than none.
For 2.x's German handbook I created copies for several pages, just to have the manual complete (and translate later), I'd rather like to avoid this for 3.0

In reply to by Jojo-Schmitz

@jojo what is a national version?

Fo the online html version:
* Go to the top index page /en/handbook
* Add a translation for your language
* You don't even need to translate the page, just save
* All the existing links will work: to the English one if there is no translation, to the translated one if there is one.

For the PDF, it is currently not possible to mix English and translated content. It's going to be translated only, unless we find a way in the code to get them mixed.

Hope this answer is somehow to the point.

In reply to by Thomas

what is a national version? the translated versions. I know I don't need to translate, just pretend and save, but I have to copy content over time and time again when the English page changes, even if the German page is not translated at all. It is a copy, made at a certain date and as such outdated by definition, I'd rather avoid that.
The translations inside MuseScore work the same way, if there is no translation, the English is used, I'd like the same model for the handbook

In reply to by Jojo-Schmitz

In the Danish page that fall back does work. I only start translate on the pages that I am going to edit. All the others automatically use the english version.
.. BUT I shure would like if the translated pages could be moved from 2. to 3. Many of the pages will need little or no modifications, and having to copy-paste all the text and go though all the links to check that they work, should really not be necessary.

In reply to by Thomas

Switch the pretty urls from musescore 2 handbook pages to musescore 3 pages.
Any chance the "old" handbooks can still have pretty urls, but in a versioned substructure?

musescore.org/handbook → current "live" one; can (for now) still link through to the /2/ version, upon releasing MS3 this forwarding is changed to forward to the /3/ version
musescore.org/3/handbook → handbook for MuseScore3
musescore.org/2/handbook → handbook for MuseScore2
musescore.org/1/handbook → handbook for MuseScore1

That way, when we link to a handbook page from the forum the link remains valid for the version that question was asked for. Especially right after releasing v3, a bunch of users will remain on v2 and links to that handbook will be required.

In reply to by Thomas

This sounds great, thanks Thomas!

We also need to start figuring out which pages will need the most changes, which pages to tackle first, who will do what, etc. I can take on some leadership in this as needed.

First step, since I had already gone ahead and did some work listing the changes we will need to document, I have now added that as a new wiki (is that really the right word?) page here on musescore.org, so from here on out anyone can edit this:


(Thomas, if you need to move this, feel free)

In reply to by Marc Sabatella

FWIW I have prepared what is intended to be a complete TOC for the Handbook (see attached).

This is meant as a base for discussing the stucture of the Handbook - and of course it expresses my opinion on that.
I have tried to fill in all the new items (marked with +) in the places I think they belong.
Feel free to use it in anyway you choose.

You may also just use it as a checklist to make sure everything is reviewed/updated.


In reply to by Thomas

I started this topic so those unfamiliar with how 3.0 will work can understand how to test new features. If those familiar with the new features can add the appropriate pages if needed and explain these, others can concentrate on making changes to the features in both.

In reply to by mike320

Definitely reasonable. We could use a strategy on how to go about this to avoid multiple people trying to work on the same pages while other pages don't get looked touched at all. Probably it will make sense to start a new thread just to track who is doing what and what is still left to do.

In reply to by Marc Sabatella

Your "Changes in MuseScore 3" could be used for follow up on the 'How to test' part.
Put an instuction at the top telling contributors to put their name next to an item, when they start writing, and put a link there when they are done. Post these 'instructions' as separate entries in the "Development" forum.
Testers can then add feedback to each item, whitout necessarily having to raise an Issue.

For the "Handbook" the handbook itself could be used. Update the TOC at the front page to cover the whole of Version 3. Put a 'TODO' label next to each page.
Add an instruction for contributors to put their name next to the page when they start writing/updating, and remove the name and the TODO label when they are finished.

Doing these two should make it easy to see how far we have progressed.
The 'marketing' to actually get people involved would be up to you @Mark Sabatella.

If you want it, I can prepare the TOC for the Handbook within a few days, based on the list in my previous post.

In reply to by neGjodsbol

That's a possibility. The document is really for more than just the Handbook, though, and since it isn't necessarily organized along the same lines as the Handbook, some items on the list probably involve changes to multiple Handbook pages, and some Handbook pages probably need updates for multiple reasons. Some pages will need no update, some will need only new screenshots and/or renaming of menu items, some will need changes to descriptions of how to accomplish a task, some will need whole new sections.

It's a lot to think about. I kind of think a separate system where we track things page by page rather than feature by feature makes sense. TODO's on the page themselves might be good enough, but maybe it would be easier if that were collected in one place?

As for TOC, I'm all for anything that makes things easier to find, but I think this probably needs to be somewhat of a community decision.

In reply to by Marc Sabatella

Maybe what we need is one author for each new feature, responsible for incorporating it into the Handbook.
One reviewer for each existing Handbook page, responsible for reveiwing and updating to make it fit with v. 3.
All combined into a single list, for tracking progress.

As for the TOC, we might have a thread for discussion og Handbook content, as you suggested earlier,

As we are preparing for updating the Handbook, maybe we could also take a look at the fonts that are used.
I specifically think of the font used to reference Menu items. Using the tag "samp class>< /samp" produces a very thin, almost unreadable text, that could realy benefit from another Font setting.

FWIW, for anyone who was waiting, string freeze was yesterday :-).

Today I plan to assess where we are and make some proposals, probably at this point in the Documentation forum since the release is getting so close to reality.

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