Éditer le Manuel

Guidelines for writing articles

Vous pourriez avoir envie de contribuer à l'écriture du Manuel de MuseScore 4 – super ! Et bienvenue.

Cette page résume les recommandations à suivre pour vous permettre de commencer à écrire des articles. Merci de la lire avec attention avant d’éditer quoi que ce soit dans notre Manuel. Ces informations sont destinées à vous aider mais, en cas de doute dans n’importe quel domaine, n’hésitez pas poser vos questions dans le forum Documentation.

Structure - General principles

Chaque page doit décrire un sujet de façon plus ou moins complète. Si vous sentez que la page devient trop longue, essayez de la diviser en pages séparées.

Toutes les pages ne sont pas identiques mais il est important de garder à l’esprit les conseils suivant de façon à faciliter la compréhension pour le lecteur :

Start with an overview

Commencez la page avec une vue d’ensemble afin d’introduire le sujet avant d’entrer dans les détails. Cette partie n’a pas forcément besoin d’un titre de chapitre.

Establish a hierarchy

Essayez d’imaginer ce que la plupart des utilisateurs peuvent chercher à réaliser et pourquoi ils peuvent avoir besoin de rechercher des informations dans le Manuel. Fournissez les solutions pour les tâches les plus communes en début de page. Celles qui sont moins usuelles peuvent être déplacées en bas de page.

Group information logically

Les éléments qui sont en relation devraient être présentés ensemble. Cela peut parfois nécessiter de discuter de fonctionnalités peu utilisées en même temps que celles qui sont d’emploi courant, mais c’est ainsi.

Focus on user tasks, not just UI components

Par exemple, une section "Créer des armures personnalisées" est préférable à "Utiliser la palette principale".

Create a table of contents

Vérifiez que l’option "Generate a table of contents" est cochée pour toutes les pages du Manuel.

Headings

Afin d’assurer une homogénéité de style pour les pages rédigées par la communauté, des titres sont déjà fournis pour de nombreuses pages. Merci de respecter cette structure. Pour les pages où ces titres manquent, vous êtes libres d’en créer, dans un style similaire à ce qui a été utilisé dans les autres pages.

Pour des raisons d’accessibilité, les titres ne doivent jamais être écrits en caractères gras. Ils nécessitent d’être mis en forme comme des étiquettes à valeur sémantique.

Toutes les pages commencent par défaut avec un titre de niveau 1 (Titre 1). L’en-tête de la première section que vous saisirez sera toujours, par conséquent, de niveau 2 (Titre 2). Assurez-vous de ne pas sauter de niveau (par exemple en passant à un niveau 4 après un niveau 2).

Niveau de titre	Utilisation et syntaxe MarkDown
Titre 1	Style par défaut pour chaque titre de page (Non modifiable par les contributeurs)
Titre 2	Use for the start of every section. MarkDown syntax: ## Heading name
Titre 3	Use for the start of every sub-section, and to introduce single-step instructions (I.e. where a list is not necessary). MarkDown syntax: ### Heading name
Titre 4	Use sparingly if additional sub-sections are required. MarkDown syntax: #### Heading name

Enfin, essayez de toujours commencer vos titres par un verbe. Par exemple : "Ajouter des indications de mesure" plutôt que "Indications de mesure"

Content

De façon générale, le Manuel de MuseScore contient deux principaux types d’informations : descriptions et instructions pratiques.

Descriptive material

Un contenu descriptif est utilisé pour expliquer les différentes zones du programme. Par exemple,

Une palette est un répertoire contenant des symboles musicaux qui peuvent être utilisés dans la partition. Les palettes par défaut de MuseScore contiennent des collections de symboles de la même famille mais vous pouvez personnaliser les palettes pour afficher à peu près tout type de symbole, ligne ou objet texte.

Le contenu descriptif tend à être un peu plus long et « étoffé » que les instructions pratiques d’emploi mais nous vous demandons d’utiliser, chaque fois que possible, un langage clair et compréhensible.

Goal-oriented instructions

Il s’agit ici d’expliquer comment réaliser une tâche spécifique. Les instructions doivent être aussi courtes et directes que possible, prenant généralement la forme de listes numérotées. Par exemple,

Pour créer une nouvelle palette

1. Ouvrir l’onglet palettes

2. Cliquer sur Ajouter des palettes

3. Cliquer sur Créer une palette personnalisée

4. Donner un nom à votre nouvelle palette et cliquer sur Créer

Remarquer que nous utilisons du texte en caractères gras pour nommer les composants de l’interface utilisateur, y compris les menus. Les raccourcis clavier comme Ctrl+S, sont mis en forme avec la balise (voir Syntaxe).

Quand vous rédigez des instructions pratiques, veillez à :

• N’utiliser que des listes numérotés (pas de points)

• Commencer chaque instruction numérotée par un verbe

• N’écrire qu’une tâche / consigne par élément numéroté

Par exemple, au lieu d’écrire cela :

1. Ouvrez l’onglet palettes et cliquez sur Ajouter des palettes

Écrivez ceci :

1. Ouvrir l’onglet palettes

2. Cliquer sur Ajouter des palettes

Pensez à inclure les raccourcis clavier dans les instructions pratiques, s’ils existent. C’est particulièrement important pour améliorer l'accessibilité du programme.

Use of non-written media

L’utilisation d’un média non écrit est encouragée en complément des descriptions écrites. Cela comprend :

• Des images GIF animées

• Des copies d’écran des parties pertinente de l’interface utilisateur

Creating animated GIFs

Les images GIF animées apportent de nombreux avantages par rapport aux copies d’écran et aux vidéos dans le sens où elles illustrent dans un minimum de temps les actions requises pour accomplir une tâche particulière. Il existe de nombreux outils disponibles pour créer des GIF ; nous recommandons toutefois le plan de travail suivant pour garantir une image claire et nette tout en minimisant le plus possible la taille du fichier (idéalement < 2 MB par GIF).

• Utilisez uniquement l’interface de MuseScore 4 et réglez son apparence en mode sombre avec surlignage bleu (pour permettre l’harmonisation tout au long du Manuel)

• Planifiez et répétez à l’avance les clics de souris et les raccourcis clavier que vous utiliserez dans l’objectif de démontrer les étapes requises dans un temps aussi court que possible (idéalement < 10 sec.)

• Utilisez un outil libre tel que gifcap pour enregistrer le contenu de votre écran

• Utilisez un outil libre tel que KeyCastr pour enregistrer les touches de clavier (si nécessaire)

• Ne montrez que la partie de l’interface utilisateur nécessaire pour la démonstration de l’action

Linking to other pages

Il est vraiment utile de faire des liens vers les autres pages du Manuel. Vous devriez le faire dès lors que vous mentionnez une partie différente de l’interface, voire pour vous référer à des versions antérieures du Manuel.

Il existe un processus spécifique pour ajouter des liens vers d’autres pages du manuel, qui permet une redirection précise sans tenir compte de la langue dans lequel la page est écrite.

Use the right syntax

[node:######,title="Nom de la page vers laquelle vous souhaitez créer un lien"]

ou, pour faire un lien vers un titre spécifique à l’intérieur d’une page :

[node:######,fragment="balise-du-titre",title="Nom de la page vers laquelle vous souhaitez créer un lien"]

Link to the page's node number, not the page's URL

Pour trouver le numéro de code (du nœud) de la page :

1. Ouvrez la page souhaitée dans votre navigateur

2. Cliquez sur l’icône "trois points" en haut et à droite de la page

3. Cliquez sur Éditer dans le menu contextuel qui s’affiche

4. Cliquez sur la barre de recherche de votre navigateur pour lire l’URL

Vous trouverez le numéro de code de page dans l’adresse URL visible dans cet écran d’édition (oui, il n’apparaît que dans ce mode). Elle ressemblera à peu près à cela : \

Use a bookmarklet to autogenerate links

Vous pouvez utiliser le programme suivant et ajoutez-le à vos favoris. Pour cela,

1. Sélectionnez l'extrait de code

2. Faites-le glisser vers la barre de favoris de votre navigateur

Vous pouvez également ajouter un nouveau signet à votre navigateur et remplacer son URL par l'extrait de code. Si vous êtes sur une page du manuel vers laquelle vous souhaitez créer un lien, cliquez sur le signet dans vos signets et copiez le lien affiché.

javascript:void function(){prompt("",`[node:${drupalSettings.path.currentPath.replace("node/","")}${document.querySelector("meta[property=\"og:title\"]").content?`,title="${document.querySelector("meta[property=\"og:title\"]").content}"`:""}${window.location.hash?`,fragment="${decodeURIComponent(window.location.hash).replace("#","")}"`:""}]`)}();

Tiré de node,title,fragment bookmarklet.

Syntax

Le manuel est essentiellement écrit en langage MarkDown, avec quelques balises HTML autorisées.

Si vous n’êtes pas familier avec MarkDown, il n’est pas long à apprendre. Commencez par lire cette page (un compte MuseScore est requis pour voir correctement le contenu de cette page, notez qu'il n'est plus possible d'utiliser de l’HTML filtré).

Examples for stuff beyond MarkDown

• Touches

  <kbd><kbd>A</kbd></kbd>, looks like A. (See Writing keyboard shortcuts below.)

• Combinaison de touches

  <kbd><kbd>Shift</kbd>+<kbd>A</kbd></kbd>, looks like Shift+A. (See Writing keyboard shortcuts below.)

• Boutons

  <kbd><samp class="button">Advanced Style Properties…</samp></kbd>, looks like Advanced Style Properties…, but this particular form is not used in the MuseScore 4 handbook (instead use bold for text that appears in the program).

• Accès au Menu

  __File→Open__, looks like File→Open

• Images

  <img src="image URL" alt="File name description" width="500px"/>, can be a useful alternative to inline images, where the image width needs to be specified

Writing keyboard shortcuts

Utilisez la syntaxe décrite plus haut et suivez les consignes suivantes :

• Pour des raisons d’accessibilité, utilisez toujours des mots plutôt que des symboles dans les noms des touches espace, touches fléchées et touches spéciales.

  • Bon : Cmd+Espace ; Win+Entrée ; Maj+Tab

  • Mauvais : ⌘+ ; ⊞+``; ⇧+↹

• Pour les touches qui représentent des caractères imprimables, utilisez le caractère approprié (par exemple écrire $ et non Dollar).

• Utilisez les abréviations communes comme Ctrl, Cmd, Échap, Suppr. Pg. Suiv. N’abrégez pas les noms de touches qui ne sont pas habituellement abrégés.

• Sauf exception, préférez Retour plutôt que Entrée et Suppr au lieu de Retour arr..

• Pour les combinaisons, saisissez les touches spéciales dans cet ordre : Win+Ctrl+Alt+Maj+Fn+… (Mac : Ctrl+Cmd+Option+Maj+Fn+…).

En cas de doute, consultez Raccourcis clavier par défaut pour voir la façon officielle d’écrire les noms des touches et leurs combinaisons.

Leaving a revision log message

Enfin, si vous avez modifié une page (que ce soit de façon importante ou non), laissez un message concis qui décrit brièvement les modifications apportées. Par exemple,

• Ajout contenu sur xxx

• Ajout images

• Correction de contenu

• Ajout de balises clavier

Laissez cette information dans le champ Message du journal de révision en fin de fenêtre Edit de chaque page :