Editing the Handbook

Guidelines for writing articles

So you'd like to contribute to the MuseScore 4 handbook – great! We're so happy you're here.

This page contains brief guidelines to get you started with writing articles. Please read this page carefully before editing anything in our handbook. This information is intended to help, but if you're in doubt about anything or have any questions, please join the discussion on the Documentation forum.

Structure - General principles

Each page should explain a single topic more or less completely. If a page feels like it is getting too long, try splitting it into separate pages.

Not every page is identical, but keeping the following in mind can help you structure your page content in a way that's easy to understand for the reader:

Start with an overview

Starting your page with an overview can help introduce a topic before launching into details. Overviews don't usually need a section heading.

Establish a hierarchy

Think about what most users will be trying to achieve, and why they might be coming to the handbook to look for information. Put solutions for the most common tasks towards the top of the page; less commonly needed information can go towards the bottom.

Group information logically

Related concepts should be discussed together. This may sometimes require less-commonly-used features to be discussed alongside more-commonly used ones, but that's okay.

Focus on user tasks, not just UI components

For instance, a section about "Creating custom key signatures" is better than a section called "Using the master palette".

Headings

Headings are used to give a structure and hierarchy to the information on the page.

The first section heading you enter will always be a Heading 1. Please also don’t skip heading levels (for example, by adding a Heading 3 after a Heading 1).

Heading level	Usage
Heading 1	Use for the start of every section.
Heading 2	Use for the start of every sub-section, and to introduce single-step instructions (i.e. where a list is not necessary).
Heading 3	Use sparingly if additional sub-sections are required.

Try to start your headings with a verb, e.g. "Adding time signatures", rather than "Time signatures".

Content

The MuseScore handbook broadly contains two main types of information: descriptive material, and goal-oriented instructions.

Descriptive material

This is used to explain different areas of the program. For example:

A Palette is a folder containing musical symbols which can be applied to the score. MuseScore's default palettes contain collections of related symbols, but you can customize palettes to display almost any kind of symbol, line or text.

Descriptive material tends to be longer and more “fleshed out” than goal-oriented instructions, but we still ask that you use simple, plain language wherever you can.

Goal-oriented instructions

These explain how to perform a specific task. The instructions should be as short and direct as possible, generally taking the form of a numbered list. For example,

To create a new palette:

1. Open the Palettes tab

2. Click Add palettes

3. Click Create custom palette

4. Name your new palette and click Create

Notice that we use bold text for named components of the user interface, including menus. Keyboard shortcuts, such as Ctrl+S, are rendered with GitBook's 'Keyboard' style.

When writing goal-oriented instructions, please:

• Use only numbered lists (no dot points)

• Begin each numbered instruction with a verb

• Write only one task/direction per numbered item

For example, instead of writing this:

1. Open the Palettes tab and click Add palettes

Please write this:

1. Open the Palettes tab

2. Click Add palettes

Please be sure to include keyboard options for goal-oriented instructions, where such options exist. This is especially important for improving the program's accessibility.

Use of non-written media

The use of non-written media is encouraged as a supplement to written descriptions. This includes:

• Animated GIFs

• Screenshots of relevant parts of the user interface

Creating animated GIFs

Animated GIFs offer many advantages over screenshots and videos in that they expose in the shortest amount of time the sequence of actions required to achieve a particular task. There are lots of tools available for creating GIFs, however we recommend the following workflow to ensure crisp and clear image quality while maintaining as small as possible file size (ideally <2MB per GIF).

• Use only the MuseScore Studio 4 interface, and set its appearance to dark mode with blue highlights (to achieve consistency across the entire handbook)

• Plan and rehearse the mouse clicks and keyboard shortcuts you will use, aiming to demonstrate the required steps in as short as possible time (ideally <10s)

• Use a free tool like gifcap to record the contents of your screen

• Use a free tool like KeyCastr to record keystrokes (where required)

• Only show the amount of UI required demonstrate a particular task