MuseScore 4 handbook update: contributions sought!
As we prepare for the release of MuseScore 4, we’d like to invite our community to participate in generating the documentation that will form our online handbook, available here on musescore.org.
Marc Sabatella, Peter Jonas and I have been working for several months to prepare a new version of the online handbook that’s both comprehensive and user-friendly. While a few elements are still being implemented, the overall chapter structure has now been established, including section sub-headings on most pages to help contributors organise the necessary content in a logical and easy-to-understand way.
We’ve made a bunch of styling changes to improve the handbook’s appearance and legibility, and are making better use of visual media (including GIFs) to show how MuseScore 4 works. We’ve also put together a helpful page of guidelines for contributors so that together, we can create a cohesive and well-written document.
The MuseScore 4 handbook will go together with a new series of videos on YouTube (also accessible from within the desktop app itself) to form a comprehensive and engaging multimedia resource.
If you enjoy writing, assembling visual content, structuring detailed information in simple and logical ways, and are keen to make a lasting contribution to what is shaping-up to be a groundbreaking release in the music software world, then we invite you to participate as a contributor to the MuseScore 4 handbook.
How to contribute
You’ll need a free account to edit pages on musescore.org. If you don’t already have one, you can create one here.
Next, we ask you to please read the page Editing the handbook.
If you then have any questions, please post them in the Documentation forum.
Next, head over to the MuseScore 4 handbook landing page. Because the handbook is still in draft status, we haven’t yet published this page at its final destination URL. This will happen at the same time as the stable release of MuseScore 4.
We recommend perusing the pages that we’ve created. You’ll find that some have already been filled with content (For example, Create your first score, Working with instruments, and the page about the Mixer). Use these as a guide to the kind of writing style and use of visual media we are looking for.
When you find a page that interests you and hasn’t already been written (It will probably contain sub-headings, but no actual content), then click on the “three dots” menu in the top right corner of the page and select “Edit”.
Editing pages
In addition to the guidelines we have published in Editing the handbook, please keep the following in mind:
- The handbook is written using Markdown. If you’re not familiar with this style, we recommend reading this page first (Note: You’ll need a musescore.com account to properly view this page).
- A handy option for auto-generating your content in Markdown is to first draft it in Google Docs, then use the free Docs to Markdown plugin to generate the required script, which you can simply paste into the Edit page.
- Whenever you make any contributions or changes to a page, please briefly note these changes (one or two lines will do) in the Revision log message field, which you’ll find in the Published panel on the right side of every Edit page.
Our team, with editorial oversight provided by Marc Sabatella and myself, will be reviewing changes as they are made. We may from time to time need to make adjustments to your content if something needs correcting, or if we’ve found a way to better articulate something in the context of the overall tone of the handbook.
Again, if you have any questions, please post them in the Documentation forum, or in the comments below. We look forward to working with you to build this valuable resource for the latest release of MuseScore.
Comments
Amazing stuff, Brad!
Hello,
what about translations into other languages? Are they done automatically by Markdown, or how does that work?
In reply to Hello, what about… by Pentatonus
There's no automatic translation.
And I'd wait with translating until there's something substantial and reasonably stable to translate
In reply to There's no automatic… by Jojo-Schmitz
Yes this is absolutely right. We will make another announcement in this forum when we're ready for translations 🙂
In reply to Hello, what about… by Pentatonus
Translation is not yet possible/enabled
Hello,
By default in MuseScore, the page color is not exactly white, but a slightly darker color. When including an image of a notation in the handbook, should the page color be changed to white to match the handbook, or left as the slightly darker color?
In reply to Hello, By default in… by ScoreAddict
Just use transparent PNGs. Usually better than JPG or GIF
In reply to Just use transparent PNGs by Jojo-Schmitz
Good suggestion. Thanks Jojo!
By the way, we do encourage GIFs where they are appropriate, particularly to show interactions with the UI. If you only need to show notation though, then a transparent PNG should be just fine.
In reply to Good suggestion. Thanks Jojo… by bradleykunda
Yes, animated GIFs are OK, else PNGs
In reply to Good suggestion. Thanks Jojo… by bradleykunda
bradleykunda wrote >> ... we encourage GIFs where appropriate, particularly to show interactions with the UI.
Why are animated GIFs encouraged? I hope there no aversion to video clips here.
Animated GIFs do have notable advantages:
• usually lightweight
• they don't require a browser plugin or codec
• excellent for really short animations that make sense when continually looped—like Tweety Bird occasionally blinking his eyes.
Animated GIFs have distinct disadvantages when used for tutorials or illustrating software interactions. The user:
• can’t pause
• can’t rewind
• can't fast forward
• no timeline "thumb" control
• can't change the playback speed
• Most frustrating : can’t easily tell where the animation ends (i.e. when it loops back to the start)
• no audio
Except for REALLY short illustrations I think the disadvantages outweigh the advantages.
Regarding the "Most frustrating" point above, I'd encourage those submitting animated GIFs to obviate the end of the animation. That could be accomplished with a technique like fade-to-black ... or some sort of identifying mark. If GIFs have an option to play once, then stop and show the play button, that would be a big improvement.
Scorster
In reply to bradleykunda wrote >> ... we… by scorster
Advantage: animated GIFs work in a PDF version of the handbook too.
In reply to Advantage: animated GIFs… by Jojo-Schmitz
But it's also possible to add a video to a PDF, although the video would surely be a considerably larger asset.
So the GIF advantage would fall under the first advantage I listed: usually lightweight.
In reply to But it's also possible to… by scorster
It won't play from within the PDF though. Opposed to an animated GIF. At least I think this to be the case
In reply to bradleykunda wrote >> ... we… by scorster
Hi Scorster,
Thanks for these points. We would indeed only be using GIFs for really short animations. Perhaps check out this page to see some examples of how I'm suggesting these could be used: https://musescore.org/en/handbook/4/create-your-first-score
Of course this is a pretty new inclusion for the MuseScore handbook, so I'm expecting we'll refine our process of making and using these kinds of visual aids as more contributors become involved in authoring content.
In reply to Hi Scorster, Thanks for… by bradleykunda
The MuseScore 3 handbook had a few animated GIFs too. See e.g https://musescore.org/en/handbook/3/notehead-schemes, at the bottom. Actually that seems to be the only one.
In reply to bradleykunda wrote >> ... we… by scorster
Why use GIF when APNG exists? It's smaller, allows transparency, allows more than 256 colors, supported by all the major browsers.
In reply to Hello, By default in… by ScoreAddict
And don't forget accessibility texts for images, I've just added some to your drum page.
Also for images with translatabe text in them better use a filename that includes a language identifier, e.g. image_en.png, so that a translation could add e.g. image_de.png
In reply to And don't forget… by Jojo-Schmitz
All text for images is great indeed, but more important for accessibility is to make sure we don't over-rely on images in the first place. That is, use images to help illustrate a process you're also explaining in words, but never as a substitute for the text explanation.
Also, on the subject of accessibility, everything needs to be explained in a way that makes it clear how to perform the action using keyboard alone, assuming there is in fact a way (and if not, an issue should be filed). That doesn't mean you mean to constantly replace references to "clicking" with references to "click or press Enter" etc - a blind user will know what "click" means to them. But it does mean, if a command is possible to execute in multiple ways, be sure to mention them all, and when discussing the keyboard method, try to keep the list of steps focused on the keyboard.
Is there an accessibility page? And could "Accessibility" also be added as a heading on the "Default keyboard shortcuts" page?
In reply to We also need pages for … by geetar
As far as I can tell this is currently missing.
Seems a pretty bad oversight
In reply to We also need pages for … by geetar
Actually is is not missing, see https://musescore.org/en/handbook/4/accessibility
In reply to Actually is is not missing,… by Jojo-Schmitz
I think "Accessibilty" should be in the "Appendix".
In reply to I think "Accessibilty"… by geetar
Debatable. I think "Viewing and Navigation" is fine
In reply to I think "Accessibilty"… by geetar
This was a deliberate decision to help blind users by giving them the info they need up front rather than forcing them to hunt down to the end for it.
Also, should "Default keyboard shortcuts" be in the "Appendix" rather than "Basics"?
In reply to IMV, "Default keyboard… by geetar
I agree. That's also where it is in the previous handbooks
In reply to IMV, "Default keyboard… by geetar
This also was a deliberate decision to expose this information better where people are more likely to see it. We've also streamlined it to show only the most common shortcuts to avoid overwhelming people, although the definition of what is "most common" is certainly up for discussion.
A full list will likely appear in the appendix as well. I'll go ahead and add the placeholder page.
BTW, both pages are not meant to be edited directly. I have produced a script to produce the relevant HTML tables directly from a file that just lists the actual shortcuts. And the names of a number of commands are likely to change soon (hopefully before the public alpha) to be more verb-focused. So I wouldn't be worrying these pages right now, other than to suggest changes as to which shortcuts make it to Basics and which do not.
I've seen snippets of the new MuseScore 4 Handbook and it looks like a significant improvement over the v3 handbook.
To enhance readability and appearance I'd recommend an indentation on ordered and unordered lists, like a left margin of .5 to 1.0 em
Like this CSS style:
ol li {
margin-left: .5em;
}
https://www.w3schools.com/CSS/css_list.asp
I know the handbook uses Markdown for editing—but that generates HTML which responds to CSS styles. Right?
Thanks for considering.
Scorster
In reply to I've seen snippets of the… by scorster
You're correct about CSS ultimately being what determines this. I don't have any particular feelings about this in particular; I'm not the design expert. But we'll see what others say!
FWIW, tomorrow in my weekly "MuseScore Café" live stream (Wednesday 12:30 PM Eastern / 16:30 GMT), I'll be talking about documentation in general, and will spend some time on the MuseScore 4 Handbook effort in particular. Anyone interested in watching and participating via the chat is welcome - see
https://community.masteringmusescore.com/c/cafe-watch/
Note you'll need to create a free account on my community site if you haven't already.
Now that that the "alpha 2" release is out and the UI is mostly finalized, we'd like to start pushing harder on getting the Handbook completed.
By my reckoning, there are about 100 pages to do. If we have 10 people volunteer to do a page a week, we'd have the whole thing done in two months. I think we can do this or better!
I've created a Google Sheets spreadsheet with links to all the Handbook pages and space to sign up for which you'd like to work on as primary contributor:
https://docs.google.com/spreadsheets/d/1SBlekCrN8CAYokinRjVWMOYR4UA4_6Q…
The purpose of the spreadsheet is to help us track what's left to do and to hopefully avoid cases of two people starting to work on the same page at the same time.
If you have questions, don't hesitate to ask here!
In reply to Now that that the "alpha 2"… by Marc Sabatella
An idea?
In reply to A better idea? Create a… by geetar
This is certainly a possibility that can be considered. But, can you explain the advantage of using a landing page here versus using the spreadsheet? I'm not saying there isn't one, but it seems like basically the same thing to me.
In reply to This is certainly a… by Marc Sabatella
My thinking is that a well-publicised in-house landings page is more likely to attract the attention of contributors than a link to an external spreadsheet buried in a thread amongst many other threads. Keeping everything in-house ensures that all changes are logged and visible to all users in "Recent changes". The landing page can be annotated and comments also appended in "Revision information" (which appears under "Log" in "Recent Changes").
In reply to Surely, a well-publicised in… by geetar
Ah, so it's more about how well-publicized it is? Of course, whatever one does to publicize a landing page on this site, can also be done to publicize a spreadsheet.
Since all actual changes to the Handbook are already logged and visible to all users, I'm not sure I understand the value of also logging the changes to the spreadsheet. Especially since Google Sheets already tracks changes. But, if someone in a position to create and publicize a page on this site understands the advantage better than I and wants to make it happen, I certainly won't stand in their way. Right now, as an ordinary user, it's easier for me to create and use spreadsheets.
In reply to Ah, so it's more about how… by Marc Sabatella
OK, a spreadsheet it is; I've already done most of the work in the "Idiomatic notation: Guitar" section, so I've marked the spreadsheet accordingly.
When I open the handbook in "printer friendly/single page" mode, it shows usernames. Guessing these are the users who last edited the page. Is that intended?
![handbook4-print-friendly-version.png]( "handbook4-print-friendly-version.png")
In reply to When I open the handbook in … by Henk De Groot
Definitely not intended! I'll bring it up with the folks who maintain the code for this.