Dokumentationsrichtlinien – MRTK2

  • Artikel
MRTK

In diesem Dokument werden die Dokumentationsrichtlinien und -standards für Mixed Reality Toolkit (MRTK) beschrieben. Dies bietet eine Einführung in die technischen Aspekte des Schreibens und Generierens von Dokumentationen, 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.

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.
  • Aufzählungszeichenlisten
    • Geschachtelte Aufzählungszeichenlisten
  • Fett formatierter Text mit **doppeltem Sternchen**
  • Kursivtext 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 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 wird use a single backtick.

Todos

Vermeiden Sie die Verwendung von TODOs in Dokumenten, da diese TODOs (z. B. Code-TODOs) im Laufe der Zeit dazu neigen, Informationen darüber zu sammeln, 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 auf Github ein neues Problem, das den Kontext hinter dem TODO beschreibt, und stellen Sie genügend Hintergrund bereit, den ein anderer Mitwirkender verstehen und dann den TODO behandeln kann.
  2. Verweisen Sie in der Dokumentation auf die Problem-URL.

<-- 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, Hinweise für allgemeine Punkte und Warnungen/wichtige Punkte nur für besondere 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 hinter dem Standard Kapiteltitels sollte als kurze Einführung in das Kapitel dienen. Machen Sie dies nicht zu lang, sondern fügen Sie Untergeordnete Ü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 sollen. Wir könnten dies irgendwann durch Vier-Ebenen-Überschriften ersetzen.

Abschnitt "Siehe auch"

Die meisten Seiten sollten mit einem Kapitel mit dem Namen Siehe auch enden. Dieses Kapitel ist einfach 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 sich nicht auf das Standard Thema beziehen. Diese sollten nicht in der Liste Siehe auch enthalten sein. 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 in einer der Dateien toc.yml des Dokumentationsordners ein Eintrag für diese Datei 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 jeder vorhandenen Toc-Datei verknüpft werden kann, um sie als Unterabschnitt zum entsprechenden Teil der Navigation hinzuzufügen.

Stil

Schreibstil

Allgemeine Faustregel: Versuchen Sie, professionell zu klingen. Dies bedeutet in der Regel, einen "Konversationston" zu vermeiden. Versuchen Sie auch, Hyperbolie und Sensationslust 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 "schlampigen Ausdrücke".
  6. Vermeiden Sie es, übermäßig aufgeregt zu klingen, wir müssen nichts verkaufen.
  7. Ebenso vermeiden Sie es, zu dramatisch zu sein. Ausrufezeichen werden selten benötigt.

Großbuchstaben

  • Verwenden Sie den Satzfall 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 sie keine beliebigen Wörter groß schreiben, auch wenn sie in diesem Kontext eine besondere Bedeutung haben. Bevorzugen Sie Kursivtext 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, wodurch die Regel der nicht willkürlichen Großschreibung im Text bricht. Verwenden Sie daher einen benutzerdefinierten Linknamen, um die Groß-/Kleinschreibung zu korrigieren. Hier finden Sie beispielsweise einen Link zur Dokumentation zu Begrenzungssteuerelementen .
  • Verwenden Sie Großbuchstaben für Namen, z. B. Unity.
  • Wenn Sie den Unity-Editor schreiben, sollte "editor" NICHT großgeschrieben werden.

Hervorhebung und Hervorhebung

Es gibt zwei Möglichkeiten, Wörter zu betonen oder hervorzuheben, indem Sie sie fett machen oder kursiv machen. Der Effekt von fett formatiertem Text ist, dass fett formatierter Text hervorsticht und daher leicht bemerkt werden kann, wenn ein Textteil überspringt oder sogar einfach über eine Seite scrollt. Fett ist großartig, um Ausdrücke hervorzuheben, die sich die Benutzer merken sollten. Verwenden Sie fett formatierten Text jedoch selten, da dies in der Regel ablenkend ist.

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 Kursivtext als einfache Methode , um etwas hervorzuheben.

Wenn ein Dateiname, ein Pfad oder ein Menüeintrag im Text erwähnt wird, sollten Sie es vorziehen, ihn kursiv zu machen, 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. Wiederholen Sie diese Hervorhebung nicht im gesamten Text, wenn sie 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: 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 denken Sie darüber nach, wie ärgerlich es wäre, wenn dieselbe Seite 20 Mal geöffnet wird.

In einen 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 verknüpften Seite ein Link zur neuen Seite hinzugefügt werden soll.

Bilder /Screenshots

Verwenden Sie Screenshots sparsam. Das Verwalten von Bildern in der Dokumentation ist viel Arbeit, und kleine Änderungen der Benutzeroberfläche können viele Screenshots veraltet machen. 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. Fügen Sie keine Elemente in einen Screenshot ein, die für das Angezeigte irrelevant sind. Erstellen Sie für instance, wenn ein Renderingeffekt angezeigt wird, einen Screenshot des Viewports, aber schließen Sie eine beliebige Benutzeroberfläche um ihn herum aus. Versuchen Sie, fenster so zu verschieben, dass nur der wichtige Teil im Image 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 alles um sie herum ausschließen.
  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 konsistenten Regeln, wie diese aussehen sollen. Zweitens ist die Wiedergabe eines solchen Screenshots ein zusätzlicher Aufwand. Beschreiben Sie stattdessen die wichtigen Teile im Text. Es gibt Ausnahmen für diese Regel, aber sie sind selten.
  5. Offensichtlich ist es viel mehr Aufwand, ein animiertes GIF neu zu erstellen. Erwarten Sie, dass Sie es bis zum Ende der Zeit neu erstellen, oder erwarten Sie, dass die 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.

Weitere Aspekte:

  • Die Editor-Benutzeroberfläche 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 sehr 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 Screenshots des 3D-Viewports. Bevorzugen Sie Die Qualität gegenüber dem Komprimierungsverhältnis.

Liste der Komponenteneigenschaften

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

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 unter dem Abschnitt Siehe auch auf anderen Seiten erwähnt werden könnte.
  3. Wenn verfügbar, lassen Sie jemand mit Kenntnissen des Themas die Seite überprüfen, um die 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, was auch eine gute Idee ist, um Feedback zu erhalten, wie verständlich die Dokumentation ist.

Quelldokumentation

Die API-Dokumentation wird automatisch aus den MRTK-Quelldateien generiert. Um dies zu ermöglichen, 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 eine Klasse, Struktur oder Enumeration dem MRTK hinzugefügt wird, muss ihr Zweck beschrieben werden. Dies ist die Form eines Zusammenfassungsblocks über 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 unter 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 Codesichtbarkeit (öffentlich, privat, geschützt und intern). Das Tool zur 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.

Für die Genehmigung eines Pull Requests ist eine PME-Dokumentation erforderlich .

Im Rahmen 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>

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

/// <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 Tooltip-Attribut von Unity zu verwenden, um die 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. 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>

Dokumentation mit Anleitung

Viele Benutzer von Mixed Reality Toolkit müssen möglicherweise nicht die API-Dokumentation 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 können zusätzliche Dateien erforderlich sein, bis zu einer pro bereitgestelltem Feature.

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

Als Teil 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 benutzerdefinierter 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 an Kunstobjekte beschreiben.

Einige Beispiele, in denen 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.

Leistungshinweise

Einige wichtige Features sind mit Leistungskosten verbunden. Häufig hängt dieser Code stark davon ab, wie sie konfiguriert werden.

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.

Aktuelle Änderungen

Die Dokumentation zu Breaking Changes besteht aus einer Datei auf oberster 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.

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 in der Featureebene breaking-changes.md Dateien enthaltenen Informationen 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 anzuzeigen.

  • Code Spell Checker: Falsch geschriebene Wörter werden unterstrichen. Sie können mit der rechten Maustaste auf ein falsches Wort klicken, um es zu ändern oder im Wörterbuch zu speichern.

Beide werden im von Microsoft veröffentlichten Dokumenterstellungspaket verpackt.

Weitere Informationen