Éditer le manuel

Recommandations pour l’écriture d’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 – Principes généraux

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 :

Commencer avec une vue d’ensemble

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.

Établir une hiérarchie

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.

Grouper les informations de façon logique

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.

Mettre en avant l’application par l’utilisateur plutôt que la description de l’interface utilisateur

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

Créer un sommaire

Vérifiez que l’option "Generate a table of contents (toutes les langues)" [générer un sommaire] est cochée pour toutes les pages du manuel.

Titres

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 structuration. 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	Utilisation	Syntaxe MarkDown
Titre 1	Style par défaut pour chaque titre de page.	(non éditable par les contributeurs)
Titre 2	Style à utiliser pour le début de chaque section.	`## Libellé du titre`
Titre 3	Style à utiliser pour le début de chaque sous-section et pour introduire des instructions en une seule étape (par exemple, lorsqu’une liste n’est pas nécessaire).	`### Libellé du titre`
Titre 4	Style à utiliser avec modération si des sous-sections supplémentaires sont nécessaires.	`#### Libellé du titre`

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

Contenu

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

Descriptions

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 également d’utiliser, chaque fois que possible, un langage clair et compréhensible.

Instructions pratiques

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 :

Ouvrez l’onglet palettes
Cliquez sur Ajouter des palettes
Cliquez sur Créer une palette personnalisée
Donnez un nom à votre nouvelle palette et cliquez sur Créer.

Remarquez 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 <kbd> (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 :

Ouvrez l’onglet palettes et cliquez sur Ajouter des palettes

écrivez ceci :

Ouvrez l’onglet palettes
Cliquez 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.

Utiliser des médias non écrits

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.

Créer des images GIF animées

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 MuseScore 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.

Faire des liens vers d’autres 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.

Utiliser la bonne syntaxe

Utilisez le format :
[node:######,title="Nom de la page de redirection"]

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 de redirection"].

Faire le lien vers le numéro de code de la page et non vers son URL

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

Ouvrez la page souhaitée dans votre navigateur
Cliquez sur l’icône "trois points" en haut et à droite de la page
Cliquez sur Éditer dans le menu contextuel qui s’affiche
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 :
Image showing where to find a page's node number

Vous pouvez utiliser le programme (bookmarlet) suivant comme « marque-page » dans vos favoris

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("#","")}"`:""}]`)}();

Source : node,title,fragment bookmarklet.

Pour créer le favori :
1. Surlignez les lignes de code
2. Faites-les glisser vers votre barre de favoris
3. Renommez si besoin ce favori (exemple : "Lien page MuseScore")

Pour utiliser le favori :
1. Ouvrez la page à référencer dans votre navigateur
2. Cliquez sur le favori créé à l’étape précédente (exemple : "Lien page MuseScore"), ce qui affiche le lien de la page en syntaxe MarkDown
3. Copiez/collez ce lien dans la page que vous rédigez

Syntaxe

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.

Remarque : 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é.

Quelques exemples pour débroussailler MarkDown :

Touches: <kbd><kbd>A</kbd></kbd> affiche A (voir Écrire des raccourcis clavier plus bas).
Combinaison de touches: <kbd><kbd>Maj</kbd>+<kbd>A</kbd></kbd> affiche Maj+A (voir Écrire des raccourcis clavier plus bas).
Boutons: <kbd><samp class="button">Propriétés de style avancé…</samp></kbd> affiche Propriétés de style avancé… mais cette forme particulière n’est normalement pas utilisée dans le manuel MuseScore 4 (utilisez à la place des caractères gras pour du texte qui apparaît dans le programme).
Accès au Menu: __Fichier → Ouvrir__ affiche Fichier → Ouvrir
Images: <img src="URL image" alt="Description de l’image ou du nom de ficher" width="500px"/> peut être utilisé de façon alternative à la commande inline quand la largeur de l’image a besoin d’être spécifiée.

Écrire des raccourcis clavier

Utilisez la syntaxe <kbd> 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, Echap, Suppr. N’abrégez pas les noms de touches qui ne sont pas habituellement abrégés (exemple : Page bas).
Sauf exception, préférez Entrée plutôt que Retour 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.

Laisser un message de révision

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 dans le journal de révision (toutes langues) en fin de fenêtre Edit de chaque page :

Message de révision