A New Chapter for the MuseScore Handbook

Hi everyone,

The MuseScore 4 Handbook is the central resource for MuseScore Studio, providing essential guidance to newcomers as well as experienced users looking to make the most of the application.

While the current documentation system has served us well for many years, it's beginning to show its age, and its limitations are becoming increasingly clear. We believe it's high time for an upgrade!

That's why we're excited to announce:

1. The MuseScore 4 Handbook is moving to GitBook.
2. Translation of the new handbook will take place on Transifex alongside translation of the desktop program.

People reading the handbook will benefit from a fresh layout, improved organization and navigation, more embedded content, and (hopefully!) more complete translations.

Why GitBook?

GitBook offers features not available in the current handbook, such as the ability to:

• Review community edits before they go live.
• Create tabbed and expandable sections.
• (More easily) embed YouTube videos and interactive content, including all Iframely-supported domains.
• Display a full table of contents for the entire handbook.
• Edit via a WYSIWYG interface in addition to Markdown source files.
• Synchronize content with a Git repository.

In addition, GitBook's rendering engine is open source, and they offer a free Community plan for open source projects.

We at Muse Group already have experience with GitBook, having used it to host the Audacity Support pages.

Why Transifex?

Although GitBook is capable of displaying translated content, it has no built-in tools to facilitate translation. Fortunately, thanks to GitBook's ability to sync content with a Git repository, we're able to extract strings and upload them to Transifex in much the same way as we have been doing with the desktop program for over a decade.

This means handbook translators will benefit from all the advanced features Transifex provides:

• Automatic notifications when source text is added or updated.
• Individual strings are marked outdated rather than the entire file (so you don't have to work out what changed).
• Ability to maintain a glossary of common terms and their agreed translations (to ensure consistency).
• Translation suggestions based on the glossary and earlier translations of similar strings.
• Translation auto-fill when a deleted string is restored.
• Automatic translation checks (e.g. to ensure it contains all HTML formatting present in the source text).
• Source structure of headings, subheadings, tables, etc. is guaranteed to be preserved in translations.
• Submitted translations can be reviewed (and marked as such) by more experienced translators.

Thanks to your efforts, the current handbook is partially translated in at least 16 languages besides English. Considering that none of the above features are available on the current handbook, that's quite an achievement!

By moving to Transifex, we hope you'll be able to help us get the handbook to a similar level of translation as MuseScore Studio itself, which is currently over 90% translated in 25 languages besides English (and partially translated in many more).

The transition

As of right now, the current handbook has been locked to prevent further contribution, but its pages will remain visible throughout the transition, and we will accept contributions at the new location once it's up and running.

The steps are as follows:

1. Review pages and transfer to GitBook
   • Starting today, we will begin systematically reviewing pages of the existing handbook and copying their content to GitBook.
   • In some cases we may decide to revert a page to an older revision if we think it's more useful than the current revision.
2. Sync to GitHub and Transifex
   • On Transifex, handbook strings will appear in a new resource alongside the existing musescore and instruments resources.
   • Sadly, it's not possible to import existing handbook translations into Transifex. Existing translations are file-based rather than string-based, and the structure of translations in the current handbook doesn't always match the structure of the English text.
3. Perform initial translation with AI model
   • To give translators a helping hand, we'll perform an initial translation with an AI model that we trained on strings & translations from the desktop program.
   • As soon as the AI is finished, translators are welcome to start checking and amending its translations, and filling in any languages that were not translated by the AI.
4. Download translations to GitHub
   • An automated script will periodically check for translations, download them, and insert them into copies of the original Markdown files.
   • These copies will be stored in separate branches of the repository, so handbook contributors don't need to checkout all languages at once on their machine.
5. Sync to language variants on GitBook
   • We have to create a variant space for each language we want the handbook to be available in.
   • This is a manual process, and we'll only do it when a language reaches a significant level of completion on Transifex.
   • Once created, the variant will automatically sync translated strings from the relevant branch on GitHub.
6. Redirect from old handbook
   • When we're ready, we'll set up a redirect from the current handbook to the new one, and update links accordingly.
   • Around this time, we will begin accepting contributions to the new handbook's English source text.

We expect this process will take about 2 weeks to complete.

During this process, we'll be making editorial decisions in the interests of clarity and brevity that may significantly alter some of the current content. In particular, we’ll be removing out-of-scope content, such as technical or musically didactic information, or details that prevent the reader from easily locating the steps needed to achieve their goals. For the new handbook, we’ll aim to provide clearer editorial guidelines to ensure the handbook remains as accessible and easy to understand as possible.

Contributing to the new handbook

Source content

Contributions to the English source text will be accepted via GitBook and GitHub. Changes made on either platform are automatically synced to the other.

GitBook has a WYSIWYG editor and visual diff, which is better for changes that affect formatting or embedded content.

GitHub shows a raw textual diff, which is better for systematic text changes, such as a find-and-replace across multiple files.

Translations

Translations of text content will take place on Transifex, including translations of URL components for handbook pages.

As with the current handbook, URL components will be limited to just lowercase ASCII letters (a-z), numeric digits (0-9), and hypen-minus (-). If necessary, we could allow some more punctuation characters (+_.), but GitBook doesn't allow anything else.

Initially, it will not be possible to submit translated versions of images or embedded content, such as screenshots or videos taken with MuseScore's UI set to a language other than English. We may enable this in the future via pull request to the handbook's repository on GitHub.