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:
- The MuseScore 4 Handbook is moving to GitBook.
- 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:
- 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.
- Sync to GitHub and Transifex
- On Transifex, handbook strings will appear in a new resource alongside the existing
musescore
andinstruments
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.
- On Transifex, handbook strings will appear in a new resource alongside the existing
- 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.
- 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.
- 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.
- 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.
Commenti
Sounds like a very good improvement, as translator I am really hoping the translated versions of images or embedded content will be added sooner rather than later as that is one the main reasons to help with the translation, as screenshots and video's not shown in the users language can be really confusing for generic users and is one of the few things not being possible when using AI or the browser to translate pages for you.
Guess it will be a matter of time before that is also possible.
Looking forward to contribute using the new solution.
I really look forward to an improvement in the indexing of the Handbook.
At present a Google search for "MuseScore Handbbook [topic]" often takes you to the obsolete MuseScore 3 Handbbook, with a message like this:
This page shows old instructions for MuseScore 3.
For MuseScore 4 users, see Lyrics.
But very rarely does the link take you directly to the required Handbook 4 section. In the example above, the link provides a long list of topics - some relevant and others virtually irrelevant. The correct Lyrics section appeared only 4th in the list, after Braille, Full Table of Contents, All keyboard shortcuts ... and then Lyrics, followed by 12 other topics which mention Lyrics.
This behaviour is crazily frustrating and inefficient. The direct link to the correct Handbook section should always appear first in the list of search results! In the "good old days" of Mu3, a Google search usually took us straight to the required Handbook section.
Sounds like a plan. Looking forward to its new and updated home.
Sounds like good news!
Along the way I hope the use of autoplaying animated GIFs is reconsidered:
https://musescore.org/en/node/371868
I know that some browsers have a means of preventing GIF autoplay, but ideally a user could experience a less hyperactive Handbook without resorting to modify their browser settings.
Consider syncing a copy from the handbook on GitBook to musescore.org.
In risposta a Consider syncing a copy from… by Thomas
AFAIK that's the plan, once the handbook is on GitBook/GitHub
In risposta a AFAIK that's the plan, once… by Jojo-Schmitz
The new handbook will be hosted on GitBook's servers, but it will appear on a subdomain of our own website, such as:
handbook.musescore.org/en
(English)handbook.musescore.org/de
(German)We're hoping to set up redirects from old handbook pages to the new pages, at least for the English handbook.
Does this mean that all the old links to pages of the Manual will be broken? Ugh!
Hi all! Just a quick update to say we're delaying the rollout of the new handbook by a few weeks while we deal with some issues that have come to our attention while reviewing the current handbook. I'll keep you posted when there's more news in this area.
In risposta a Hi all! Just a quick update… by shoogle
...we're delaying the rollout ...while we deal with some issues that have come to our attention while reviewing the current handbook.
Hopefully, you will minimize using quick-playing animated GIF files which make information assimilation and comprehension difficult - especially when viewed by someone trying to learn something new.
While not a GIF file, here's an example of the case in point:
(Important steps just fly by! :-)
I completely understand your frustration. The search results for the MuseScore 4 Handbook can be a bit chaotic right now, especially with the outdated MuseScore 3 pages still appearing in the results. It’s clear that Google’s indexing isn’t prioritizing the most relevant pages for MuseScore 4 users, which makes finding the correct information much more time-consuming than it should be.
Improving the indexing and ensuring that the most accurate and up-to-date Handbook sections appear first in the search results would certainly make the user experience much smoother. This could involve adjusting how the Handbook pages are indexed or updating metadata on the website to clearly distinguish MuseScore 4 content from older versions.
It’s also a good idea for users to directly bookmark or use specific URLs for MuseScore 4-related content until the search results are more optimized. Hopefully, the team behind MuseScore will prioritize improving this indexing issue in future updates, making it as easy as it was with MuseScore 3 to get directly to the needed Handbook section!
In risposta a I completely understand your… by patterroni82
Personally, I download the Manual and use Acrobat's search function. I realize that doesn't include updates. I have no problem with GIF's. I find them helpful.