MuseScore 4 handbook update: contributions sought!

• 14 Juin 2022 - 16:52

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.

Commentaires

• 14 Juin 2022 - 23:13

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?

Screenshot 2022-06-14 151037.jpg

Répondre

• 16 Juin 2022 - 00:04

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

Répondre

• 16 Juin 2022 - 07:43

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.

Répondre

• 15 Juin 2022 - 14:09

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.

Répondre

• 20 Juin 2022 - 13:54

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.

Répondre

• 21 Juin 2022 - 22:07

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

Répondre

• 21 Juin 2022 - 22:23

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.

Répondre

• 15 Août 2022 - 22:32

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!

Répondre

• 16 Août 2022 - 11:17

An idea?

  1. Create a temporary landing page for the MS4 handbook on this website, with a list of chapter titles each linked to the corresponding handbook page. Make the landing page editable so that contributors can annotate it.
  2. To work on a page, a contributor puts his/her user name and the note "Work in progress" next to the relevant chapter title on the landing page. This means that the user is working on it right now.
  3. When the user wants to "clock off" s/he removes the "Work in progress" and substitutes "Completed awaiting checking" or "Completed sections X to Y".
  4. When the page has been checked, put up the notice "Completed and checked" next to the chapter title.
  5. The landing page can be deleted when all work is completed.

Répondre

• 16 Août 2022 - 17:43

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").

Répondre

• 16 Août 2022 - 18:56

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.

Répondre

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