3.0 Handbook
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.
Comments
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 Absolutely, we need to start… by Marc Sabatella
In short, it's easier to use the 2.0 process that still exists except you can keep both staves in a grand staff hidden or shown if applicable. All of the other uses you explained that exist are redundant and add nothing to the ease or capabilities of the program.
In reply to In short, it's easier to use… 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 It's mostly true () that … by Marc Sabatella
I'm just happy I dont have to write the handbook entry on this topic.
To me it seems the user will get lost long before having ready about (and understood) the many combinations and permutations.
In reply to I'm just happy I dont have… 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 Back to the real issue. When… by neGjodsbol
I'd expect a string freeze some time between a Beta and an RC, that might be the right time to start the localization. At least no later than that
In reply to Back to the real issue. When… 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 The Handbook has always been… 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 The Handbook has always been… 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 Back to the real issue. When… by neGjodsbol
With all the new features on the way, it's easy to forget all the smaller changed that have been made, which may require updates to the handbook.
Maybe developers should be encouraged to provide info on these.
Not necessarily writing the handbook, just highligts.
Here's a document I created to track the changes that will require documentation:
https://docs.google.com/document/d/1opwLokba5VETrRC--7jrLPehIP8paLLAmnR…
I started a new thread dedicated to discussing that document:
https://musescore.org/en/node/277968
Discussion of how to deal with the Handbook itself can stay here.
In reply to Here's a document I created… 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 Whether we create… 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 Here's a document I created… 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.
https://musescore.org/en/handbook
The other is a simple listing of the autogenerated Outline.
https://musescore.org/en/handbook-0
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 One thing we might look at,… by neGjodsbol
One is for the online html handbook, the other the source for the PDF version
In reply to One is for the online html… by Jojo-Schmitz
Why then is it that if you select 'handbook' at the top of a page, you get returned to the Pdf page.
Seems weird to me.
EDIT:
Anyway the Pdf download might be better placed as one of many ressources available from a new 'Get help' entry point.
In reply to Why then is it that if you… 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 Actually, my hope is to have… by Marc Sabatella
Could indeed be either PDF or HTML, but if the latter then better as a single page (like this), this HTML is an order of magnitude smaller than the PDF (<700K vs. >7M)
In reply to Could indeed be either PDF… 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 Why would you prefer a… by Marc Sabatella
...it took forever to display the HTML page on my computer.
In reply to ...it took forever to… by mike320
That too :-)
In reply to ...it took forever 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 Because it get generated on… 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 The Resource Manager seems… by Marc Sabatella
Download as one zip archive would be also an option, yes.
In reply to Why would you prefer a… by Marc Sabatella
The Pdf is a known and proven way og downloading.
If you want to go the HTML route, you should try to get it ready for testing soon.
In reply to The Pdf is a known and… by neGjodsbol
The HTML pages are used on use on a daily basis, online, the PDFs much less
In reply to The HTML pages are on use on… by Jojo-Schmitz
Packaging, distribution with ressource manager, unpacking and installation locally, and linked to a Help-menu entry, could have pitfalls, that we need to handle.
Would you aim for a local copy to have multilingual support?
In reply to Packaging, distribution with… 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 Could you explain what… 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 Should maybe have said… 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 Understood, and of course… by Marc Sabatella
You do want to access the handbook from the Help-menu, right?
So dont you need to make up your mind on HTML or PDF?
In reply to You do want to access the… 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 Packaging, distribution with… by neGjodsbol
Definitely multi-lingual
What I'd like the 3.0 handbook to do better that the 2.x one: have a fixed structure in all languages and automatically fall back to the English page when there is no translation available, just like in MuseScore itself. That way every translation is always
In reply to Definitely multi-langual 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 I haven't seen problems with… 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 Perhaps when the English… by mike320
I like the idea.
Maybe we could also have a list in each language with all outdated pages, to help translators.
Somewhat like the list of untranslated words in Tx.
In reply to Perhaps when the English… by mike320
That 'mark out of date' mechanism is in place, just not automatic. And for good reason: fixing a typo in the English handbook doesn't invalidate the German translation
In reply to That mechanism is in place,… 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:
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 @Jojo, what you say is true,… by mike320
If this could be done, it would be a great help.
May also be used by other than translators, that just wish to stay updated.
In reply to Why then is it that if you… by neGjodsbol
@neGjodsbol thanks for bringing this issue to our attention. We improved the breadcrumb link to always link back to the handbook toc page, rather than the handbook top placeholder page.
In reply to Here's a document I created… 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.
Index
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.
In reply to Besides the technical and… by neGjodsbol
The installation chapter should remain part of the handbook, even if it isn't needed for the offline doc MuseScore may bring along
Updates have not (yet) become automatic (just for Mac so far? And for the Windows Store version, but won't happen for Linux)
In reply to Besides the technical and… by neGjodsbol
These are good suggestions. To avoid things becoming too difficult to follow, though, I will start a new thread specifically to deal with content.
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
Community work
Final server side work
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 Hi everyone, thanks for… 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 _ consider opening up the… 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 @jojo what is a national… 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 the translated versions. I… 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 In the Danish page that fall… by neGjodsbol
That works for all pages? not just for https://musescore.org/da/handbog
Hmm, apparently so. Not the question is how did you do that or how did that happen or how could I miss this. And how can I make use of this now (like delete some translations so the English originals show instead of my copies)?
In reply to That works for all pages?… by Jojo-Schmitz
@Jojo what you described used to be the case in the past, before we started using the [ node:node_id,title="val2" ] syntax. With that syntax, the problem you described went away.
In reply to @Jojo what you described… by Thomas
OK, then I seem to need an 'untranslate' or 'remove translation'
In reply to Hi everyone, thanks for… 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 Switch the pretty urls from… by jeetee
@jeetee not a bad idea. Will think about it.
In reply to Hi everyone, thanks for… 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:
https://musescore.org/en/changes-musescore-3
(Thomas, if you need to move this, feel free)
In reply to This sounds great, thanks… by Marc Sabatella
@Marc https://musescore.org/en/changes-musescore-3 is fine. And for your information, the preparations on the server side as explained at https://musescore.org/en/node/277749#comment-869043 have started as of today. Keeping you posted when it's in place.
In reply to This sounds great, thanks… 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.
TableOfContents.txt
In reply to Hi everyone, thanks for… by Thomas
The server side preparations are in place now for handbook 3. Here is the main toc page: https://musescore.org/en/handbook-3
Translations are not enabled for now and the PDF is not generated either for this new handbook. Focus for now lays on editing the book content.
If there are issues, don't hesitate to report.
Edit away!
In reply to The server side preparations… 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 I started this topic so… 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 Definitely reasonable. We… 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 Your "Changes in MuseScore 3… 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 That's a possibility. The… 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.