Freigeben über

Dokumentationsrichtlinien — MRTK2

MRTK

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

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

Funktionalität und Markup

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

  1. Nummerierte Listen
    1. Geschachtelte nummerierte Listen mit mindestens 3 führenden Leerzeichen
    2. Die tatsächliche Zahl im Code ist irrelevant; Bei der Analyse wird die richtige Artikelnummer festgelegt.
  • Listen mit Aufzählungszeichen
    • Geschachtelte Aufzählungszeichenlisten
  • Fett formatierter Text mit **doppeltem Sternchen**
  • Kursiv formatierterText mit _unterstrich_ oder *einzelnem Sternchen*
  • 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 den drei Backticks "", und geben csharp als Sprache für die Syntaxmarkierung an:

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

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

TODOs

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

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

  1. Melden Sie ein neues Problem auf GitHub, das den Kontext hinter dem TODO beschreibt, und geben Sie genügend Hintergrundinformationen an, die ein anderer Mitwirkender verstehen und dann den TODO behandeln kann.
  2. Verweisen Sie in der Dokumentation auf die Problem-URL im Todo.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Ein kurzer Klappentext zum Thema -->

Hervorgehobene Abschnitte

Verwenden Sie > [! HINWEIS] , > [! WARNUNG] , und > [! WICHTIG] , um die folgenden Stile zu erzeugen. Es wird empfohlen, Notizen für allgemeine Punkte und Warnungen/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 Standard Kapiteltitel sollte als kurze Einführung dienen, worum es in diesem Kapitel geht. Machen Sie dies nicht zu lang, sondern fügen Sie untere Überschriften hinzu. Diese ermöglichen das Verknüpfen von Abschnitten und können als Lesezeichen gespeichert werden.

Haupttext

Verwenden Sie Überschriften mit zwei und drei Ebenen, um den Rest zu strukturieren.

Miniabschnitte

Verwenden Sie eine fett formatierte Textzeile für Blöcke, die hervorstechen sollten. Wir könnten dies irgendwann durch Vier-Ebenen-Überschriften ersetzen.

Abschnitt "Siehe auch"

Die meisten Seiten sollten mit einem Kapitel namens Siehe auch enden. Dieses Kapitel ist lediglich eine Aufzählung von Links zu Seiten, die sich auf dieses Thema beziehen. Diese Links können ggf. auch innerhalb des Seitentexts angezeigt werden, dies ist jedoch nicht erforderlich. Ebenso kann der Seitentext Links zu Seiten enthalten, die nicht mit dem Standard Thema zusammenhängen. Diese sollten nicht in die Liste Siehe auch aufgenommen werden. Sehen Sie sich das Kapitel "Siehe auch" dieser Seite als Beispiel für die Auswahl von Links an.

Inhaltsverzeichnis

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

Format

Schreibstil

Allgemeine Faustregel: Versuchen Sie, professionell zu klingen. Das bedeutet in der Regel, einen "Gesprächston" zu vermeiden. Versuchen Sie auch, Hyperbel und Sensationalismus zu vermeiden.

  1. Versuchen Sie nicht, (über) lustig zu sein.
  2. Schreiben Sie niemals "I"
  3. Vermeiden Sie "wir". Dies kann in der Regel einfach umformuliert werden, indem stattdessen "MRTK" verwendet wird. 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 "schlupfigen Ausdrücke".
  6. Vermeiden Sie es, übermäßig aufgeregt zu klingen, wir müssen nichts verkaufen.
  7. Vermeiden Sie es auf ähnliche Weise, übermäßig dramatisch zu sein. Ausrufezeichen sind selten erforderlich.

Großschreibung

  • Verwenden Sie die Groß-/Kleinschreibung für Überschriften. Ie. Großbuchstaben des ersten Buchstabens und der Namen, aber nichts anderes.
  • Verwenden Sie reguläres Englisch für alles andere. Das bedeutet, dass beliebige Wörter nicht groß geschrieben werden, auch wenn sie in diesem Kontext eine besondere Bedeutung haben. Bevorzugen Sie kursiv formatierten Text zum Hervorheben bestimmter Wörter, siehe unten.
  • Wenn ein Link in einen Satz eingebettet ist (dies ist die bevorzugte Methode), verwendet der Standardkapitelname immer Großbuchstaben und bricht damit die Regel, dass keine beliebige Großschreibung im Text vorhanden ist. Verwenden Sie daher einen benutzerdefinierten Linknamen, um die Groß-/Kleinschreibung zu korrigieren. Hier sehen Sie beispielsweise einen Link zur Dokumentation des Begrenzungssteuerelements .
  • Verwenden Sie Großbuchstaben für Namen, z. B. Unity.
  • Verwenden Sie beim Schreiben des Unity-Editors NICHT die Großschreibung "Editor".

Hervorhebung und Hervorhebung

Es gibt zwei Möglichkeiten, Wörter hervorzuheben oder hervorzuheben, indem Sie sie fett oder kursiv gestalten. Der Effekt von fett formatiertem Text ist, dass fett formatierter Text hervorsticht und daher leicht bemerkt werden kann, wenn ein Textabschnitt übersprungen oder sogar einfach über eine Seite gescrollt wird. Fett ist großartig, um Phrasen hervorzuheben, die sich die Leute merken sollten. Verwenden Sie fett formatierten Text jedoch selten, da er in der Regel ablenkt.

Oft möchte man entweder etwas "gruppieren", das logisch zusammengehört, oder einen bestimmten Begriff hervorheben, weil er eine besondere Bedeutung hat. Solche Dinge müssen nicht aus dem Gesamttext herausragen. Verwenden Sie kursiv formatierten Text als einfache Methode , um etwas hervorzuheben.

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

Versuchen Sie im Allgemeinen, unnötige Textmarkierungen zu vermeiden. Sonderbegriffe können einmal hervorgehoben werden, um den Leser darauf aufmerksam zu machen, nicht wiederholen Sie solche Hervorhebungen im gesamten Text, wenn es keinen Zweck mehr erfüllt und nur ablenkt.

Erwähnen von Menüeinträgen

Wenn Sie einen Menüeintrag erwähnen, auf den ein Benutzer klicken soll, lautet die aktuelle Konvention: Projektdateien >> Blatt erstellen >

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 denken Sie darüber nach, wie ärgerlich es wäre, wenn dieselbe Seite 20 Mal geöffnet wird.

In einem Satz eingebettete Links bevorzugen:

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

Überlegen Sie beim Hinzufügen eines Links, ob er auch im Abschnitt Siehe auch aufgeführt werden soll. Überprüfen Sie auf ähnliche Weise, ob der seite mit Verknüpfung ein Link zur neuen Seite hinzugefügt werden soll.

Bilder/Screenshots

Verwenden Sie Screenshots sparsam. Das Verwalten von Bildern in der Dokumentation ist eine Menge Arbeit, kleine Änderungen an der Benutzeroberfläche können dazu führen, dass viele Screenshots veraltet sind. Die folgenden Regeln reduzieren den Wartungsaufwand:

  1. Verwenden Sie keine Screenshots für Dinge, die im Text beschrieben werden können. Insbesondere sollten Sie niemals einen Screenshot eines Eigenschaftenrasters zum alleinigen Zweck der Anzeige von Eigenschaftsnamen und -werten ausführen.
  2. Schließen Sie keine Elemente in einen Screenshot ein, die für das Angezeigte irrelevant sind. Wenn für instance ein Renderingeffekt angezeigt wird, erstellen Sie einen Screenshot des Viewports, schließen Sie jedoch alle ui-Elemente aus, die ihn umgeben. Wenn Sie eine Benutzeroberfläche anzeigen, versuchen Sie, Fenster so zu verschieben, dass nur dieser wichtige Teil im Bild enthalten ist.
  3. Wenn Sie die Screenshot-Benutzeroberfläche einschließen, zeigen Sie nur die wichtigen Teile an. Wenn Sie beispielsweise über Schaltflächen in einer Symbolleiste sprechen, erstellen Sie ein kleines Bild, das die wichtigen Symbolleistenschaltflächen zeigt, aber schließen Sie alles um sie herum aus.
  4. Verwenden Sie nur Bilder, die einfach zu reproduzieren sind. Das bedeutet, dass Sie keine Marker oder Hervorhebungen in Screenshots zeichnen. Erstens gibt es sowieso keine einheitlichen 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. Offensichtlich ist es viel mehr Aufwand, ein animiertes GIF zu erstellen. Erwarten Sie, dass Sie es bis zum Ende der Zeit neu erstellen, oder erwarten Sie, dass Benutzer es auswerfen, wenn sie diese Zeit nicht verbringen möchten.
  6. Halten Sie die Anzahl der Bilder in einem Artikel niedrig. Häufig ist es eine gute Methode, einen Screenshot eines Tools zu erstellen, das alles zeigt, und dann den Rest in Text zu beschreiben. Dies erleichtert das Ersetzen des Screenshots bei Bedarf.

Einige andere Aspekte:

  • Die Benutzeroberfläche des Editors für Screenshots sollte den hellgrauen Design-Editor verwenden, da nicht alle Benutzer Zugriff auf das dunkle Design haben und wir die Dinge 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 stark 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 vor Komprimierungsverhältnis bevorzugen.

Liste der Komponenteneigenschaften

Wenn Sie eine Liste von Eigenschaften dokumentieren, verwenden Sie fetten Text, um den Eigenschaftennamen hervorzuheben, dann Zeilenumbrüche und regulärer Text, um sie zu beschreiben. Verwenden Sie keine Unterkapitel oder Aufzählungen.

Vergessen Sie auch nicht, alle Sätze mit einem Punkt zu beenden.

Checkliste für Seitenabschluss

  1. Stellen Sie sicher, dass die Richtlinien dieses Dokuments befolgt wurden.
  2. Durchsuchen Sie die Dokumentstruktur, und überprüfen Sie, ob das neue Dokument im Abschnitt Siehe auch auf anderen Seiten erwähnt werden könnte.
  3. Wenn verfügbar, bitten Sie jemanden mit Kenntnissen über das Thema, die Seite zur technischen Korrektheit zu lesen.
  4. Bitten Sie jemanden, die Seite für Stil und Formatierung zu lesen. Dies kann jemand sein, der mit dem Thema nicht vertraut ist. Dies ist auch eine gute Idee, um Feedback zu erhalten, wie verständlich die Dokumentation ist.

Quelldokumentation

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

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

Klassen-, Struktur- und Enumerationszusammenfassungsblöcke

Wenn dem MRTK eine Klasse, Struktur oder Enumeration hinzugefügt wird, muss deren Zweck beschrieben werden. Dies ist die Form eines Zusammenfassungsblocks oberhalb der -Klasse.

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

Wenn Abhängigkeiten auf Klassenebene vorhanden sind, sollten diese 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 sind mit Zusammenfassungsblöcken zu dokumentieren, unabhängig von der Sichtbarkeit von Code (öffentlich, privat, geschützt und intern). Das Tool für die Dokumentationsgenerierung ist dafür verantwortlich, nur die öffentlichen und geschützten Features herauszufiltern und zu veröffentlichen.

HINWEIS: Für Unity-Methoden (z. B. "Awake", "Start", "Update") ist kein Zusammenfassungsblock erforderlich.

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

Als Teil eines PME-Zusammenfassungsblocks ist 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>

Feature-Einfü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 empfiehlt sich, das QuickInfo-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 Inhalt der QuickInfo 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.")]

Enumeration values

Beim Definieren und Aufzählen muss code auch die Bedeutung der Enumerationswerte mithilfe eines Zusammenfassungsblocks dokumentieren. Hinweisblö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>

Anleitungsdokumentation

Viele Benutzer von Mixed Reality Toolkit 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. Je nach Größe und/oder Komplexität eines bestimmten Featurebereichs sind möglicherweise zusätzliche Dateien erforderlich, bis zu einer pro bereitgestelltem Feature.

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

Im Rahmen dieser Dokumentation sollten Anleitungsabschnitte, einschließlich Abbildungen, bereitgestellt werden, um Kunden, die mit einem Feature oder Konzept vertraut sind, bei den ersten Schritten zu unterstützen.

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 MRTK. Um dies für Kunden so reibungslos wie möglich zu gestalten, sollten Komponenten Entwurfsdokumentationen bereitstellen, die formatierungs- oder andere Anforderungen für Kunstobjekte beschreiben.

Einige Beispiele, in denen die Entwurfsdokumentation hilfreich sein kann:

  • Cursormodelle
  • Visualisierungen für räumliche Zuordnungen
  • 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 auch nicht.

Leistungshinweise

Einige wichtige Features haben Leistungseinbußen. Häufig hängt dieser Code stark davon ab, wie sie konfiguriert sind.

Zum 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 sind in der API - und Übersichtsdokumentation enthalten.

Breaking Changes

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

Zum 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, die in der Featureebene breaking-changes.md Dateien enthalten sind, 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 Extension for Visual Studio Code : Verwenden Sie ALT+M, um ein Menü mit Dokumenterstellungsoptionen anzuzeigen.

  • Codeschreibprüfung – 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.

Beide sind im von Microsoft veröffentlichten Dokumenterstellungspaket enthalten.

Siehe auch

  • Last updated on