Das Handbuch bearbeiten

Updated ein Jahr ago

    Leitfaden für das Verfassen von Artikeln

    Sie möchten also zum Handbuch von MuseScore 4 beitragen - großartig! Wir sind froh, dass Sie hier sind.

    Diese Seite enthält einen kurzen Leitfaden, um Ihnen den Einstieg in das Schreiben von Artikeln zu erleichtern. Bitte lesen Sie sich diese Seite sorgfältig durch, bevor Sie etwas in unserem Handbuch bearbeiten. Diese Hinweise sollen Ihnen eine Hilfe sein. Sollten Sie sich aber im Zweifelsfall nicht sicher sein oder Fragen haben, dann beteiligen Sie sich bitte an der Diskussion im deutschsprachigen oder englischsprachigen Forum zur Dokumentation.

    Gliederung - Allgemeine Grundsätze

    Jede Seite sollte ein einzelnes Thema mehr oder weniger vollständig darstellen. Falls Sie das Gefühl haben, dass eine Seite zu lang wird, versuchen Sie diese in einzelne Seiten aufzuteilen.

    Nicht jede Seite ist gleich. Wenn Sie aber die folgenden Hinweise beachten, kann es Ihnen dabei helfen, den Inhalt der Seite so zu strukturieren, dass er für die Leser leicht verständlich ist:

    Beginnen Sie mit einem Überblick

    Bevor Sie sich den Einzelheiten zuwenden, ist es hilfreich mit einer kurzen Übersicht das Thema der Seite vorzustellen. Überblicke brauchen üblicherweise keine Abschnittsüberschrift.

    Eine Hierarchie aufstellen

    Überlegen Sie, was die meisten Benutzerinnen und Benutzer zu erreichen versuchen und warum sie das Handbuch aufrufen um nach Informationen zu suchen. Stellen Sie Lösungen für die häufigsten Probleme an den Anfang der Seite,. Informationen, die weniger häufig benötigt werden, können an den Schluss gerückt werden.

    Informationen logisch gruppieren

    Verwandte Konzepte sollten zusammen erläutert werden. Manchmal kann dies erfordern, dass weniger oft genutzte Funktionen neben häufiger genutzten erörtert werden. Das ist aber in Ordnung.

    Auf die Aufgaben der Benutzer konzentrieren, nicht nur auf die UI-Komponenten

    Ein Abschnitt "Eigene Tonarten erstellen" ist beispielsweise besser geeignet als ein Abschnitt mit Titel "Verwendung der Master-Palette".

    Inhaltsverzeichnis erstellen

    Vergewissern Sie sich, dass die Option "Generate a table of contents" ("Inhaltsverzeichnis generieren") für jede Seite des Handbuchs aktiv ist.

    Überschriften

    Wir streben einen einheitlichen Stil für von der Community geschriebene Seiten an. Daher haben wir auf vielen Seiten bereits Überschriften angelegt. Bitte strukturieren Sie Ihren Inhalt entsprechend dieser Vorgaben. Für Seiten ohne Überschriften können Sie eigene erstellen. Wählen Sie dabei einen Stil ähnlich dem der anderen Seiten.

    Aus Gründen der Barrierefreiheit sollten Überschriften niemals als normaler Fettdruck formatiert werden. Alle Überschriften müssen mittels semantisch bedeutsamer Tags als solche definiert werden.

    Alle Seiten beginnen standardmäßig mit einer Überschrift der Ebene 1. Die erste Abschnittsüberschrift, die Sie hinzufügen, ist daher immer eine Überschrift der Ebene 2. Bitte überspringen Sie auch keine Überschriftenebenen (indem Sie z. B. eine Überschrift 4 nach einer Überschrift 2 einfügen).

    Überschriftenebene Verwendung Markdown-Syntax
    Überschrift 1 Standard für alle Seitentitel (kann von Mitwirkenden nicht editiert werden)
    Überschrift 2 Zu verwenden bei jedem Beginn eines neuen Abschnitts. ## Meine Überschrift
    Überschrift 3 Zu verwenden bei jedem Beginn eines neuen Unterabschnitts und um einzelne Schritte einer Schritt-für-Schritt-Anweisung einzuleiten (also dort, wo eine Auflistung nicht nötig ist). ### Meine Überschrift
    Überschrift 4 Sparsam zu verwenden, falls zusätzliche Unterabschnitte notwendig sind. #### Meine Überschrift

    Und schließlich sollten Sie versuchen, Ihre Überschriften immer mit einem Verb zu beginnen, also z. B. "Hinzufügen von Taktarten" und nicht "Taktarten".

    Inhalt

    Das MuseScore-Handbuch enthält im Grunde zwei verschiedene Arten von Informationen: beschreibendes Wissen und zielorientierte Anweisungen.

    Beschreibendes Wissen

    Es dient dazu, unterschiedliche Anwendungsbereiche des Programms zu erklären. Zum Beispiel,

    Eine Palette ist ein Verzeichnis musikalischer Symbole, die auf die Partitur angewendet werden können. Die Standardpaletten von MuseScore enthalten eine Auswahl ähnlicher Symbole, Sie können die Paletten jedoch anpassen, um praktisch jede Art von Symbol, Linie oder Text einzubinden.

    Beschreibendes Wissen ist in der Regel umfangreicher und ausführlicher als zielorientierte Anweisungen. Wir bitten Sie trotzdem, eine einfache, klare Sprache zu verwenden, wann immer es möglich ist. (siehe auch "Top 10 Principles for Plain Language" in Englisch)

    Zielorientierte Anweisungen

    Damit wird erklärt, wie eine bestimmte Aufgabe ausgeführt werden soll. Die Anweisungen sind so kurz und präzise wie möglich zu halten und haben im Allgemeinen die Form einer nummerierten Liste. Zum Beispiel,

    Um eine benutzerdefinierte Palette zu erstellen

    1. Öffnen Sie den Tab Paletten
    2. Klicken Sie auf Paletten hinzufügen
    3. Klicken Sie auf Benutzerdefinierte Palette erstellen
    4. Benennen Sie Ihre benutzerdefinierte Palette und klicken Sie auf Erstellen

    Wir verwenden Fettdruck für namentlich genannte Komponenten der Benutzeroberfläche, einschließlich Menüs. Tastaturkürzel, wie z. B. Strg+S, werden durch <kbd> Tags erzeugt (siehe Syntax).

    Wenn Sie eine Anweisung erstellen, beachten Sie bitte:

    • Verwenden Sie nur nummerierte Listen (keine Aufzählungszeichen wie Bullet Points).
    • Beginnen Sie jede nummerierte Anweisung mit einem Verb.
    • Formulieren Sie nur eine Tätigkeit/Anweisung pro nummerierten Punkt.

    Zum Beispiel, anstatt zu schreiben:

    1. Öffnen Sie den Tab Paletten und klicken Sie auf Paletten hinzufügen

    Schreiben Sie bitte:

    1. Öffnen Sie den Tab Paletten
    2. Klicken Sie auf Paletten hinzufügen

    Bitte beziehen Sie Tastaturbefehle für zielorientierte Anweisungen ein, sofern solche Befehle vorhanden sind. Dies ist insbesondere für die Verbesserung der Barrierefreiheit des Programms wichtig.

    Verwendung von nicht-schriftlichen Medien

    Das Einbinden von nicht-schriftlichen Medien wird als sinnvolle Ergänzung zu schriftlichen Beschreibungen empfohlen. Das schließt ein:

    • Animierte GIFs
    • Screenshots von relevanten Teilen der Benutzeroberfläche

    Animierte GIFs erstellen

    Animierte GIFs bieten viele Vorteile gegenüber Screenshots und Videos, da sie die Abfolge von Schritten, die zum Bewältigen einer bestimmten Aufgabe erforderlich sind, in kürzester Zeit veranschaulichen. Es gibt viele Tools zur Erstellung von GIFs, wir empfehlen jedoch den folgenden Ablauf, um eine gute Bildqualität zu gewährleisten und gleichzeitig die Dateigröße so klein wie möglich zu halten (idealerweise <2MB pro GIF).

    • Verwenden Sie ausschließlich die Benutzeroberfläche von MuseScore 4 und legen Sie deren Darstellung auf den dunklen Modus mit Akzentfarbe Blau fest (um Einheitlichkeit im gesamten Handbuch zu gewährleisten).
    • Planen und proben Sie die Mausklicks und Tastaturbefehle, die Sie verwenden werden. Ziel soll es sein, die benötigten Schritte in so kurzer Zeit wie möglich zu demonstrieren (idealerweise <10s).
    • Verwenden Sie ein freies Tool wie gifcap um den Inhalt Ihres Bildschirms aufzuzeichnen.
    • Verwenden Sie ein freies Tool wie KeyCastr um Tastatureingaben aufzuzeichnen (falls erforderlich).
    • Stellen Sie nur den Bereich der Benutzeroberfläche dar, der benötigt wird um eine bestimmte Tätigkeit zu veranschaulichen.

    Verlinkung auf andere Seiten

    Es ist sehr hilfreich, auf andere Seiten des Handbuchs zu verlinken. Sie dürfen dies immer dann tun, wenn Sie einen anderen Teil der Benutzeroberfläche erwähnen, oder selbst dann, wenn Sie auf ältere Versionen des Handbuchs verweisen.

    Es gibt ein eigenes Vorgehen um Verlinkungen auf andere Handbuchseiten hinzuzufügen, das unabhängig von der jeweiligen Sprachversion korrekte Verlinkungen ermöglicht.

    Verwendung der korrekten Syntax

    [node:######,title="Name der Seite, auf die verlinkt werden soll"]

    oder, um auf eine bestimmte Überschrift innerhalb der Seite zu verlinken:

    [node:######,fragment="Überschriften-Schlüssel",title="Name der Seite, auf die verlinkt werden soll"]

    Verlinkung auf eine Handbuchseite mittels Knotennummer (node), nicht URL

    Um die Knotennummer einer Handbuchseite zu ermitteln:

    1. Öffnen Sie die gewünschte Seite in Ihrem Browser.
    2. Klicken Sie auf das "Drei-Punkte"-Symbol oben rechts auf der Seite.
    3. Klicken Sie auf Bearbeiten innerhalb des erscheinenden Kontextmenüs.
    4. Klicken Sie auf die Adressleiste Ihres Browsers um die URL zu lesen.

    Sie finden die Knotennummer der Seite innerhalb der URL-Adresse dieser Bearbeiten-Seite (die Knotennummer ist nur auf der Bearbeiten-Seite sichtbar). Sie sieht beispielsweise wie folgt aus:
    Image showing where to find a page's node number

    Bookmarklet um Links automatisch zu erzeugen

    Den folgenden Codeausschnitt können Sie als Bookmarklet Ihren Lesezeichen hinzufügen. Dazu

    1. Selektieren Sie den Codeausschnitt.
    2. Ziehen Sie diesen (drag and drop) in die Lesezeichenleiste Ihres Browsers.

    Alternativ können Sie ein neues Lesezeichen in Ihrem Browser erstellen und die Lesezeichen-URL durch den Codeausschnitt ersetzen. Wenn Sie sich auf einer Seite innerhalb des Handbuchs befinden, auf die Sie verlinken wollen, klicken Sie auf das Bookmarklet in Ihren Lesezeichen und kopieren Sie den angezeigten Link.

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

    Aus Artikel node,title,fragment bookmarklet im Forum.

    Syntax

    Das Handbuch ist in Markdown verfasst mit einigen zulässigen HTML-Tags.

    Sollten Sie mit Markdown nicht vertraut sein, ist es in kurzer Zeit erlernbar. Beginnen Sie damit, zunächst diese Seite zu lesen (in Englisch, ein MuseScore-Konto ist nötig, um den Inhalt dieser Seite richtig anzuzeigen; beachten Sie auch, dass Sie Filtered HTML nicht mehr verwenden können).

    Beispiele jenseits von Markdown

    Tasten
    <kbd><kbd>A</kbd></kbd> wird dargestellt als A. (Siehe unten: Schreiben von Tastaturkürzeln)
    Tastenkombinationen
    <kbd><kbd>Shift</kbd>+<kbd>A</kbd></kbd> wird dargestellt als Shift+A. (Siehe unten: Schreiben von Tastaturkürzeln)
    Buttons (Schaltflächen)
    <kbd><samp class="button">Erweiterte Stileigenschaften…</samp></kbd> wird dargestellt als Erweiterte Stileigenschaften…. Allerdings wird diese spezielle Darstellungsform im MuseScore 4 Handbuch nicht verwendet (nutzen Sie stattdessen Fettdruck um Textinhalte der Programmoberfläche darzustellen).
    Menüpunkte
    __Datei&rarr;Öffnen__ wird dargestellt als Datei→Öffnen
    Bilder
    <img src="Bild-URL" alt="Dateinamenbeschreibung" width="500px"/> kann eine sinnvolle Alternative zu eingebundenen Bildern (inline image) sein, bei denen die Bildbreite angegeben werden muss.

    Schreiben von Tastaturkürzeln

    Benutzen Sie die oben beschriebene <kbd>-Syntax und beachten Sie die folgenden Hinweise:

    • Aus Gründen der Barrierefreiheit sollten Sie für Leer-, Pfeil- und Sondertasten immer Wörter anstelle von Symbolen verwenden.

      • Gut: Cmd+Leertaste; Win+Eingabe; Umschalt+Tab

      • Schlecht: ⌘+    ; ⊞+⏎; ⇧+↹

    • Für Tasten, die druckbare Symbole darstellen, sollte das entsprechende Zeichen verwendet werden (z. B. schreiben Sie $ und nicht Dollar).

    • Verwenden Sie gängige Abkürzungen wie Strg, Cmd, Esc, Entf, Alt. Kürzen Sie keine Tastennamen ab, die normalerweise nicht abgekürzt werden.

    • Bevorzugen Sie, sofern dies nicht von Bedeutung ist, Eingabe anstelle von Enter und Entf anstelle von Rücktaste.

    • Bei der Verwendung von Tastenkombinationen schreiben Sie die Sondertasten in dieser Reihenfolge: Win+Strg+Alt+Umschalt+Fn+… (Mac: Ctrl+Cmd+Option+Umschalt+Fn+…).

    Im Zweifelsfall sollten Sie die Standard-Tastaturkürzel (Default keyboard shortcuts) nachschlagen, um zu erfahren, wie die Tastennamen und -kombinationen zu schreiben sind.

    Eine Meldung im Revisionsprotokoll hinterlassen

    Wenn Sie eine Seite ändern (egal wie groß oder klein!), hinterlassen Sie bitte eine kurze Nachricht, in der Sie die Änderungen zusammenfassen. Zum Beispiel,

    • Inhalt zu xxx ergänzt
    • Bild hinzugefügt
    • Inhalt korrigiert
    • Tastaturbefehle hinzugefügt

    Hinterlassen Sie diese Nachricht im Textfeld Änderungsmitteilung (Revision log message) der Bearbeiten-Seite jeder Seite:

    Revision log text field