Dokumentationsrichtlinien


Funktionalität und Markup

In diesem Abschnitt werden häufig benötigte Features beschrieben. Sehen Sie sich den Quellcode der Seite an, um zu sehen, wie sie funktionieren.

  1. Nummerierte Listen
    1. Geschachtelte nummerierte Listen mit mindestens drei führenden Leerzeichen
    2. Die tatsächliche Zahl im Code ist irrelevant. Die Analyse sorgt für das Festlegen der richtigen Elementnummer.
  • Aufzählungen
    • Geschachtelte Aufzählungen
  • Fett formatierten Text mit **doppeltem Sternchen**
  • italischerText mit _underscore_ oder *single asterisk*
  • Text highlighted as code innerhalb eines Satzes "using backquotes"
  • Links zu Dokumentationsseiten MRTK-Dokumentationsrichtlinien
  • Links zu Ankern innerhalb einer Seite; Anker werden gebildet, indem Leerzeichen durch Bindestriche ersetzt und in Kleinbuchstaben konvertiert werden.

Für Codebeispiele verwenden wir die Blöcke mit drei Backticks "", und geben csharp als Sprache für die Syntaxhervorhebung an:

int SampleFunction(int i)
{
   return i + 42;
}

Wenn Code in einem Satz erwähnt use a single backtick wird.

Todos

Vermeiden Sie die Verwendung von TODOs in Dokumentationen, da diese TODOs (z. B. Code-TODOs) im Laufe der Zeit dazu tendieren, sich anzusammeln und Informationen darüber zu erhalten, wie sie aktualisiert werden sollten und warum verloren geht.

Wenn das Hinzufügen eines ToDO unbedingt erforderlich ist, führen Sie die folgenden Schritte aus:

  1. Erstellen Sie ein neues Problem auf GitHub, das den Kontext hinter dem TODO beschreibt, und stellen Sie genügend Hintergrund zur Verfügung, damit ein anderer Mitwirkender den ToDO verstehen und dann beheben kann.
  2. Verweisen Sie in der Dokumentation auf die Problem-URL in der Todo-Datei.

<!-- TODO: https://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE Ein kurzer Weichtext zum Problem –>

Hervorgehobene Abschnitte

Um bestimmte Punkte für den Leser hervorzuheben, verwenden Sie [! HINWEIS] , [! WARNUNG] und [! WICHTIG] , um die folgenden Stile zu erzeugen. Es wird empfohlen, Hinweise für allgemeine Punkte und Warnungs-/wichtige Punkte nur für spezielle relevante Fälle zu verwenden.

Hinweis

Beispiel für eine Notiz

Warnung

Beispiel für eine Warnung

Wichtig

Beispiel für einen wichtigen Kommentar

Seitenlayout

Einführung

Der Teil direkt nach dem Haupttitel des Kapitels sollte als kurze Einführung dienen, worum es in diesem Kapitel geht. Lassen Sie dies nicht zu lang, sondern fügen Sie untergeordnete Überschriften hinzu. Diese ermöglichen das Verknüpfen mit Abschnitten und können als Lesezeichen gespeichert werden.

Hauptteil

Verwenden Sie Zwei- und Dreiebenen-Überschriften, um den Rest zu strukturieren.

Miniabschnitte

Verwenden Sie eine fett formatierten Textzeile für Blöcke, die hervorgehoben werden sollten. Wir könnten dies zu einem bestimmten Zeitpunkt durch Vier-Level-Überschriften ersetzen.

Abschnitt "Siehe auch"

Die meisten Seiten sollten mit einem Kapitel namens Siehe auch enden. Dieses Kapitel ist einfach eine Aufzählung von Links zu Seiten, die sich auf dieses Thema bezieht. Diese Links werden möglicherweise auch im Seitentext angezeigt, dies ist jedoch nicht erforderlich. Ebenso kann der Seitentext Links zu Seiten enthalten, die nicht mit dem Hauptthema verknüpft sind. Diese sollten nicht in der Liste Siehe auch enthalten sein. Im Kapitel "Siehe auch" dieser Seite finden Sie ein Beispiel für die Auswahl von Links.

Inhaltsverzeichnis (Inhaltsverzeichnis)

Toc-Dateien werden zum Generieren der Navigationsleisten in der MRTK-Dokumentation github.io verwendet. Wenn eine neue Dokumentationsdatei hinzugefügt wird, stellen Sie sicher, dass in einer der dateien toc.yml des Dokumentationsordners ein Eintrag für diese Datei enthalten ist. Nur Artikel, die in den Toc-Dateien aufgeführt sind, werden in der Navigation der Entwickler-Dokumentation angezeigt. Es kann eine Toc-Datei für jeden Unterordner im Dokumentationsordner vorhanden sein, die mit einer vorhandenen Toc-Datei verknüpft werden kann, um sie als Unterabschnitt zum entsprechenden Teil der Navigation hinzuzufügen.

Stil

Schreibstil

Allgemeine Faustregel: Versuchen Sie, professionelle zu klingt. Dies bedeutet in der Regel, einen "Konversationston" zu vermeiden. Versuchen Sie auch, Hyperbole und Zierlichkeiten zu vermeiden.

  1. Versuchen Sie nicht, (zu viel) zu sein.
  2. Schreiben Sie nie "I".
  3. Vermeiden Sie "we". Dies kann in der Regel einfach mithilfe von "MRTK" umformuliert werden. Beispiel: "Wir unterstützen dieses Feature": > "MRTK unterstützt dieses Feature" oder "Die folgenden Features werden unterstützt...".
  4. Versuchen Sie auf ähnliche Weise, "Sie" zu vermeiden. Beispiel: "Mit dieser einfachen Änderung wird Ihr Shader konfigurierbar!" – "Shader können mit wenig Aufwand > konfigurierbar gemacht werden."
  5. Verwenden Sie keine "schrägen Ausdrücke".
  6. Vermeiden Sie es, zu aufgeregt zu klingen, da wir nichts verkaufen müssen.
  7. Vermeiden Sie ebenso, zu drastisch zu sein. Ausrufezeichen werden selten benötigt.

Großbuchstaben

  • Verwenden Sie satzfall für Überschriften. Ie. Großbuchstaben und Namen, aber nichts anderes.
  • Verwenden Sie für alles andere reguläres Englisch. Das bedeutet, dass sie keine beliebigen Wörter großmachen, auch wenn sie in diesem Kontext eine besondere Bedeutung haben. Bevorzugen Sie italischen Text zum Hervorheben bestimmter Wörter, siehe unten.
  • Wenn ein Link in einen Satz eingebettet ist (dies ist die bevorzugte Methode), verwendet der Standardname des Kapitels immer Großbuchstaben, wodurch die Regel der nicht willkürlichen Groß-/Kleinbuchstaben im Text verletzt wird. Verwenden Sie daher einen benutzerdefinierten Linknamen, um die Groß-/A-Groß-/Groß-/A-Setzung zu korrigieren. Hier finden Sie beispielsweise einen Link zur Dokumentation zur Begrenzungssteuerung.
  • Groß-/Groß-/Großnamen, z. B. Unity.
  • Großschreiben Sie "Editor" NICHT, wenn Sie den Unity-Editor schreiben.

Hervorhebung und Hervorhebung

Es gibt zwei Möglichkeiten, Wörter hervorzuheben oder hervorzuheben, um sie fett zu formatieren oder sie italisch zu machen. Der Effekt von fett formatiertem Text ist, dass fetter Text nicht angezeigt wird und daher leicht bemerkt werden kann, wenn ein Textteil übersprungen oder sogar einfach über eine Seite gescrollt wird. Fett ist sehr gut, um Ausdrücke hervorzuheben, die sich die Menschen merken sollten. Verwenden Sie fett formatierten Text jedoch selten,da dies im Allgemeinen abgelenkt ist.

Häufig möchte man etwas , das logisch zusammengehörig ist, "gruppiert" oder einen bestimmten Begriff hervorheben, da er eine besondere Bedeutung hat. Solche Dinge müssen sich nicht vom gesamten Text abhingen. Verwenden Sie italischen Text als einfache Methode, um etwas hervorzuheben.

Wenn ein Dateiname, ein Pfad oder ein Menüeintrag im Text erwähnt wird, bevorzugen Sie es, es kursalisch zu machen, um ihn logisch zu gruppieren, ohne störend zu sein.

Versuchen Sie im Allgemeinen, unnötige Texthervorhebungen zu vermeiden. Spezielle Begriffe können einmal hervorgehoben werden, um den Leser darauf aufmerksam zu machen. Wiederholen Sie diese Hervorhebung nicht im gesamten Text, wenn sie keinen Zweck mehr erfüllt und nur abgelenkt ist.

Erwähnen von Menüeinträgen

Wenn ein Menüeintrag erwähnt wird, auf den ein Benutzer klicken soll, ist die aktuelle Konvention: Project Files Create >> Leaf

Fügen Sie so viele nützliche Links wie möglich zu anderen Seiten ein, aber jeder Link nur einmal. Angenommen, ein Leser klickt auf jeden Link auf der Seite und überlegen, wie lästig es wäre, wenn dieselbe Seite 20 Mal geöffnet wird.

Links bevorzugen, die in einen Satz eingebettet sind:

Vermeiden Sie externe Links. Sie können veraltet sein oder urheberrechtlich geschützte Inhalte enthalten.

Wenn Sie einen Link hinzufügen, sollten Sie überlegen, ob er auch im Abschnitt Siehe auch aufgeführt werden soll. Überprüfen Sie auf ähnliche Weise, ob der Seite, die mit verknüpft ist, ein Link zur neuen Seite hinzugefügt werden soll.

Bilder/Screenshots

Verwenden Sie Screenshots mit geringem Nutzen. Die Verwaltung von Bildern in der Dokumentation ist sehr arbeitsaufwänd, kleine Änderungen an der Benutzeroberfläche können dazu führen, dass viele Screenshots veraltet sind. Die folgenden Regeln verringern den Wartungsaufwand:

  1. Verwenden Sie keine Screenshots für Dinge, die in Text beschrieben werden können. Erstellen Sie insbesondere niemals einen Screenshot eines Eigenschaftenrasters, um nur Eigenschaftennamen und -werte zu zeigen.
  2. Schließen Sie keine Dinge in einen Screenshot ein, die für die Angezeigten irrelevant sind. Wenn z. B. ein Renderingeffekt angezeigt wird, erstellen Sie einen Screenshot des Viewports, schließen Sie jedoch alle benutzeroberflächen um ihn herum aus. Wenn Sie eine Benutzeroberfläche anzeigen, versuchen Sie, Fenster so zu verschieben, dass nur dieser wichtige Teil im Bild zu sehen ist.
  3. Wenn Sie die Screenshot-Benutzeroberfläche einschließen, zeigen Sie nur die wichtigen Teile an. Wenn Sie z. B. über Schaltflächen in einer Symbolleiste sprechen, erstellen Sie ein kleines Bild, das die wichtigen Symbolleistenschaltflächen anzeigt, aber alles um sich herum ausschließt.
  4. Verwenden Sie nur Bilder, die einfach zu reproduzieren sind. Das bedeutet, dass Sie keine Marker oder Hervorhebungen in Screenshots zeichnen. Erstens gibt es keine konsistenten Regeln, wie diese aussehen sollten. Zweitens ist das Reproduzieren eines solchen Screenshots ein zusätzlicher Aufwand. Beschreiben Sie stattdessen die wichtigen Teile im Text. Es gibt Ausnahmen von dieser Regel, aber sie sind selten.
  5. Natürlich ist es viel aufwendiger, ein animiertes GIF neu zu erstellen. Erwarten Sie, dass sie bis zum Ende der Zeit neu erstellt werden soll, oder erwarten Sie, dass Personen sie auslösen, wenn sie diese Zeit nicht aufwenden möchten.
  6. Halten Sie die Anzahl der Bilder in einem Artikel gering. Häufig ist es eine gute Methode, einen Gesamtscreenshot eines Tools zu erstellen, das alles zeigt, und dann den Rest im Text zu beschreiben. Dies erleichtert es, den Screenshot bei Bedarf zu ersetzen.

Einige andere Aspekte:

  • Die Benutzeroberfläche des Editors für Screenshots sollte den Editor für hellgraue Designs verwenden, da nicht alle Benutzer Zugriff auf das dunkle Design haben und wir die Konsistenz so konsistent wie möglich halten möchten.
  • Die Standardbildbreite beträgt 500 Pixel, da dies auf den meisten Monitoren gut angezeigt wird. Versuchen Sie nicht, zu viel davon abzuweichen. Die Breite sollte maximal 800 Pixel betragen.
  • Verwenden Sie PNGs für Screenshots der Benutzeroberfläche.
  • Verwenden Sie PNGs oder JPGs für 3D-Viewport-Screenshots. Qualität gegenüber Komprimierungsverhältnis bevorzugen.

Liste der Komponenteneigenschaften

Verwenden Sie beim Dokumentieren einer Liste von Eigenschaften fetten Text, um den Eigenschaftennamen zu markieren, und verwenden Sie dann Zeilenumbrüche und regulären Text, um sie zu beschreiben. Verwenden Sie keine Unterkapitel oder Aufzählungslisten.

Vergessen Sie außerdem nicht, alle Sätze mit einem Punkt fertig zu stellen.

Prüfliste für seitenseitige Vervollständigung

  1. Stellen Sie sicher, dass die Richtlinien dieses Dokuments eingehalten wurden.
  2. Durchsuchen Sie die Dokumentstruktur, und überprüfen Sie, ob das neue Dokument im Abschnitt Siehe auch auf anderen Seiten erwähnt werden kann.
  3. Falls verfügbar, sollten Sie jemanden mit Kenntnissen zum Thema bitten, die Seite auf technische Richtigkeit zu überprüfen.
  4. Bitten Sie jemanden, die Seite für Stil und Formatierung zu lesen. Dies kann jemand sein, der mit dem Thema nicht vertraut ist. Es ist auch eine gute Idee, Feedback dazu zu erhalten, wie verständlich die Dokumentation ist.

Quelldokumentation

Die API-Dokumentation wird automatisch aus den MRTK-Quelldateien generiert. Um dies zu vereinfachen, müssen Quelldateien Folgendes enthalten:

Darüber hinaus sollte der Code gut kommentiert werden, um Wartung, Fehlerbehebungen und eine einfache Anpassung zu ermöglichen.

Klassen-, Struktur- und Enumerationszusammenfassungsblöcke

Wenn dem MRTK eine Klasse, Struktur oder Enumeration hinzugefügt wird, muss ihr Zweck beschrieben werden. Dies erfolgt in Form eines Zusammenfassungsblocks über der -Klasse.

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Wenn Abhängigkeiten auf Klassenebene vorhanden sind, sollten sie in einem Hinweisblock direkt unterhalb der Zusammenfassung dokumentiert werden.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

Pull Requests, die ohne Zusammenfassungen für Klassen, Strukturen oder Enumerationen übermittelt werden, werden nicht genehmigt.

Eigenschaften-, Methoden- und Ereigniszusammenfassungsblöcke

Eigenschaften, Methoden und Ereignisse (PMEs) sowie Felder müssen unabhängig von der Codesichtbarkeit (öffentlich, privat, geschützt und intern) mit Zusammenfassungsblöcken dokumentiert werden. Das Tool zur Dokumentationsgenerierung ist dafür verantwortlich, nur die öffentlichen und geschützten Features heraus zu filtern und zu veröffentlichen.

HINWEIS: Ein Zusammenfassungsblock ist für Unity-Methoden nicht erforderlich (z. B. "Aktualisieren", "Starten", "Aktualisieren").

Die PME-Dokumentation ist erforderlich, damit ein Pull Request genehmigt werden kann.

Als Teil eines PME-Zusammenfassungsblocks sind die Bedeutung und der Zweck von Parametern und zurückgegebenen Daten erforderlich.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Featureeinführungsversion und Abhängigkeiten

Im Rahmen der API-Zusammenfassungsdokumentation sollten Informationen zur MRTK-Version, in der das Feature eingeführt wurde, und alle Abhängigkeiten in einem Hinweisblock dokumentiert werden.

Abhängigkeiten sollten Erweiterungs- und/oder Plattformabhängigkeiten enthalten.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Serialisierte Felder

Es ist eine bewährte Methode, das ToolTip-Attribut von Unity zu verwenden, um Laufzeitdokumentation für die Felder eines Skripts im Inspektor bereitzustellen.

Damit Konfigurationsoptionen in der API-Dokumentation enthalten sind, müssen Skripts mindestens den QuickInfo-Inhalt in einen Zusammenfassungsblock einschließen.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Enumerationswerte

Beim Definieren und Aufzählen muss code auch die Bedeutung der Enumerationswerte mithilfe eines Zusammenfassungsblocks dokumentieren. Anmerkungsblöcke können optional verwendet werden, um zusätzliche Details bereitzustellen, um das Verständnis zu verbessern.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Dokumentation mit Anleitung

Viele Benutzer des Mixed Reality Toolkits müssen die API-Dokumentation möglicherweise nicht verwenden. Diese Benutzer nutzen unsere vorgefertigten, wiederverwendbaren Prefabs und Skripts, um ihre Erfahrungen zu erstellen.

Jeder Featurebereich enthält eine oder mehrere Markdowndateien (MD), die auf einer relativ hohen Ebene beschreiben, was bereitgestellt wird. Abhängig von der Größe und/oder Komplexität eines bestimmten Featurebereichs sind möglicherweise zusätzliche Dateien erforderlich, bis zu einer pro bereitgestellter Funktion.

Wenn ein Feature hinzugefügt wird (oder die Nutzung geändert wird), muss eine Übersichtsdokumentation bereitgestellt werden.

Im Rahmen dieser Dokumentation sollten Anleitungsabschnitte, einschließlich Abbildungen, bereitgestellt werden, um Kunden zu helfen, die noch nicht mit einem Feature oder Konzept bei den ersten Schritte begonnen haben.

Entwurfsdokumentation

Mixed Reality bietet die Möglichkeit, völlig neue Welten zu schaffen. Ein Teil davon ist wahrscheinlich die Erstellung von benutzerdefinierten Ressourcen für die Verwendung mit dem MRTK. Damit dies für Kunden so reibungslos wie möglich ist, sollten Komponenten eine Entwurfsdokumentation bereitstellen, in der alle Formatierungs- oder anderen Anforderungen für Diess-Objekte beschrieben werden.

Einige Beispiele, in denen die Entwurfsdokumentation hilfreich sein kann:

  • Cursormodelle
  • Visualisierungen der räumlichen Zuordnung
  • Soundeffektdateien

Diese Art von Dokumentation wird dringend empfohlen und kann im Rahmen einer Pull Request-Überprüfung angefordert werden.

Dies kann sich von der Entwurfsempfehlung auf der MS Developer-Website unterscheiden oder nicht.

Leistungshinweise

Einige wichtige Features sind mit Leistungskosten verbunden. Dieser Code hängt häufig davon ab, wie sie konfiguriert sind.

Beispiel:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

Leistungshinweise werden für CPU- und/oder GPU-starke Komponenten empfohlen und können im Rahmen einer Pull Request-Überprüfung angefordert werden. Alle anwendbaren Leistungshinweise müssen in der API- und Übersichtsdokumentation enthalten sein.

Aktuelle Änderungen

Die Dokumentation zu Breaking Changes besteht aus einer Datei der obersten Ebene, die mit den einzelnen breaking-changes.md jedes Featurebereichs verknüpft ist.

Der Funktionsbereich breaking-changes.md Dateien enthält die Liste aller bekannten Breaking Changes für ein bestimmtes Release sowie den Verlauf der Breaking Changes aus früheren Releases.

Beispiel:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

Die Informationen auf Featureebene breaking-changes.md Dateien werden in den Versionshinweisen für jedes neue MRTK-Release aggregiert.

Alle Breaking Changes, die Teil einer Änderung sind, müssen als Teil eines Pull Requests dokumentiert werden.

Tools zum Bearbeiten von MarkDown

Visual Studio Code ist ein hervorragendes Tool zum Bearbeiten von Markdowndateien, die Teil der MRTK-Dokumentation sind.

Beim Schreiben der Dokumentation wird auch dringend empfohlen, die folgenden beiden Erweiterungen zu installieren:

  • Docs Markdown-Erweiterung für Visual Studio Code: Verwenden Sie ALT+M, um ein Menü mit Dokumenterstellungsoptionen auf die Seite zu öffnen.

  • Rechtschreibprüfung für Code: Falsch geschriebene Wörter werden unterstrichen. Klicken Sie mit der rechten Maustaste auf ein falsch geschriebenes Wort, um es zu ändern oder im Wörterbuch zu speichern.

Beides ist im von Microsoft veröffentlichten Docs Authoring Pack enthalten.

Siehe auch

MRTK

In diesem Dokument werden die Dokumentationsrichtlinien und -standards für das Mixed Reality Toolkit (MRTK) beschrieben. Dies bietet eine Einführung in technische Aspekte der Dokumentationserstellung und -generierung, um häufige Fallstricke hervorzuheben und den empfohlenen Schreibstil zu beschreiben.

Die Seite selbst sollte als Beispiel dienen, daher verwendet sie den beabsichtigten Stil und die gängigsten Markupfeatures der Dokumentation.