Dokumentationsrichtlinien — MRTK2

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 des Schreibens und Der Generation von Dokumentationen, um häufige Fallstricke hervorzuheben und den empfohlenen Schreibstil zu beschreiben.

Die Seite selbst soll als Beispiel dienen, daher wird sie die beabsichtigte Formatvorlage und die am häufigsten verwendeten Markupfeatures der Dokumentation verwendet.


Funktionalität und Markup

In diesem Abschnitt werden häufig erforderliche Features beschrieben. Wenn Sie sehen möchten, wie sie funktionieren, schauen 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; Die Analyse kümmert sich um das Festlegen der richtigen Elementnummer.
  • Aufzählungen mit Aufzählungen
    • Verschachtelte Aufzählungszeichenlisten
  • Text fett formatiert mit **Double Asterisk**
  • Kursivtext mit _unterstrich_ oder *einzelnes Sternchen*
  • Text highlighted as code in einem Satz "using backquotes"
  • Links zu Dokumentationsseiten MRTK-Dokumentationsrichtlinien
  • Links zu Verankerungen innerhalb einer Seite; Anker werden gebildet, indem Leerzeichen durch Striche 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 Syntaxmarkierung an:

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

Beim Erwähnen von Code innerhalb eines Satzes 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 und zu erfahren, wie sie aktualisiert werden sollten und warum verloren geht.

Wenn es unbedingt erforderlich ist, einen TODO hinzuzufügen, führen Sie die folgenden Schritte aus:

  1. Dateiieren Sie ein neues Problem auf Github, das den Kontext hinter dem TODO beschreibt, und stellen Sie genügend Hintergrund bereit, den ein anderer Mitwirkender verstehen und dann an den TODO adressieren könnte.
  2. Verweisen Sie auf die Problem-URL im Aufgaben-Todo in den Dokumenten.

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

Hervorgehobene Abschnitte

Verwenden Sie > [! HINWEIS] , > [! WARNUNG] und > [! WICHTIG] , um die folgenden Formatvorlagen zu erzeugen. Es wird empfohlen, Notizen 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 Hauptkapiteltitel sollte als kurze Einführung dienen, was das Kapitel betrifft. Machen Sie dies nicht zu lang, sondern fügen Sie Unterüberschriften hinzu. Diese ermöglichen das Verknüpfen mit Abschnitten und können als Lesezeichen gespeichert werden.

Haupttext

Verwenden Sie zweistufige und dreistufige Überschriften, um den Rest zu strukturieren.

Miniabschnitte

Verwenden Sie eine fett formatierte Textzeile für Blöcke, die hervorzuheben sind. Wir könnten dies an einigen Stellen durch vier Ebenen ersetzen.

Abschnitt "Siehe auch"

Die meisten Seiten sollten mit einem Kapitel mit dem Namen "Siehe" 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 nicht im Zusammenhang mit dem Hauptthema stehen, dies sollte 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 (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 es einen Eintrag für diese Datei in einer der Toc.yml-Dateien des Dokumentationsordners gibt. Nur in den Toc-Dateien aufgeführte Artikel werden in der Navigation der Entwicklerdokumente angezeigt. Es kann eine Toc-Datei für jeden Unterordner im Dokumentationsordner vorhanden sein, der 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 , professionell zu klingen. Das bedeutet in der Regel, einen "Unterhaltungston" zu vermeiden. Versuchen Sie auch, Hyperbole und Sensationalismus zu vermeiden.

  1. Versuchen Sie nicht, (übermäßig) lustig zu sein.
  2. Schreibe nie 'I'
  3. Vermeiden Sie "wir". Dies kann in der Regel einfach neu formuliert 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 auch, "Sie" zu vermeiden. Beispiel: "Mit dieser einfachen Änderung wird Ihr Shader konfigurierbar!" -> "Shader können mit wenig Aufwand konfigurierbar gemacht werden."
  5. Verwenden Sie nicht "sloppy phrases".
  6. Vermeiden Sie es, übermäßig aufgeregt zu klingen, wir müssen nichts verkaufen.
  7. Ebenso vermeiden Sie es, übermäßig dramatisch zu sein. Ausrufezeichen sind selten erforderlich.

Großbuchstaben

  • Verwenden Sie "Satzfall" für Überschriften. Ie. Großbuchstaben und Namen, aber nichts anderes.
  • Verwenden Sie normales Englisch für alles andere. Das bedeutet , dass beliebige Wörter nicht großgeschrieben werden, auch wenn sie eine besondere Bedeutung in diesem Kontext haben. Bevorzugen Sie Kursivtext zum Hervorheben bestimmter Wörter , siehe unten.
  • Wenn ein Link in einen Satz eingebettet ist (dies die bevorzugte Methode ist), verwendet der Standardkapitelname immer Großbuchstaben, wodurch die Regel keine beliebige Großschreibung innerhalb von Text zerbricht. Verwenden Sie daher einen benutzerdefinierten Linknamen, um die Groß-/Kleinschreibung zu beheben. Im Folgenden sehen Sie beispielsweise einen Link zur Dokumentation der Begrenzungssteuerelemente .
  • Verwenden Sie großgeschriebene Namen, z. B. Unity.
  • "Editor" beim Schreiben des Unity-Editors nicht großgeschrieben.

Hervorhebung und Hervorhebung

Es gibt zwei Möglichkeiten, Wörter hervorzuheben oder hervorzuheben, sie fett zu gestalten oder kursiv zu machen. Der Effekt fett formatierter Text besteht darin, dass fett formatierter Text ausgeblendet wird und daher leicht bemerkt werden kann, während sie einen Textabschnitt überspringen oder sogar einfach über eine Seite scrollen. Fett ist großartig, um Ausdrücke hervorzuheben, die sich die Menschen merken sollten. Verwenden Sie jedoch selten fett formatierten Text, da sie im Allgemeinen ablenkend ist.

Häufig möchte man entweder etwas gruppieren, das logisch zusammen gehört oder einen bestimmten Begriff hervorhebung, weil er eine besondere Bedeutung hat. Solche Dinge müssen nicht vom Gesamttext abstehen. Verwenden Sie Kursivtext als einfache Methode , um etwas hervorzuheben.

Wenn ein Dateiname, ein Pfad oder ein Menüeintrag im Text erwähnt wird, empfiehlt es sich, kursiv zu gruppieren, ohne ablenkend zu sein.

Versuchen Sie generell, unnötige Textmarkierungen zu vermeiden. Sonderbegriffe können einmal hervorgehoben werden, um den Leser darauf aufmerksam zu machen, diese Hervorhebung nicht im gesamten Text zu wiederholen, wenn es keinen Zweck mehr bietet 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 > Dateien > erstellen Blatt erstellen >

Fügen Sie so viele nützliche Links zu anderen Seiten wie möglich 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.

Bevorzugen Sie Links, die in einen Satz eingebettet sind:

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

Berücksichtigen Sie beim Hinzufügen eines Links, ob sie auch im Abschnitt "Siehe auch " aufgeführt werden soll. Überprüfen Sie ebenso, ob der verknüpften Seite ein Link zu der neuen Seite hinzugefügt werden soll.

Bilder / Screenshots

Verwenden Sie Screenshots sparsam. Die Verwaltung von Bildern in der Dokumentation ist viel Arbeit, kleine UI-Änderungen 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 screenshotn Sie niemals ein Eigenschaftenraster für den alleinigen Zweck, Eigenschaftennamen und -werte anzuzeigen.
  2. Fügen Sie keine Elemente in einen Screenshot ein, die für die angezeigten Elemente irrelevant sind. Wenn z. B. ein Renderingeffekt angezeigt wird, erstellen Sie einen Screenshot des Viewports, schließen jedoch alle Ui um sie herum aus. Wenn Sie eine Benutzeroberfläche anzeigen, versuchen Sie, Fenster so zu verschieben, dass nur der 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 anzeigt, aber alles um sie herum ausschließen.
  4. Verwenden Sie nur Bilder, die leicht zu reproduzieren sind. Das bedeutet, dass keine Markierungen oder Hervorhebungen in Screenshots dargestellt werden. Erstens gibt es keine konsistenten Regeln, wie diese aussehen sollten, trotzdem. Zweitens ist die Wiedergabe eines solchen Screenshots zusätzlichen 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 bis zum Ende der Zeit neu erstellt werden soll, oder erwarten Sie, dass die Benutzer es auswerfen, wenn sie diese Zeit nicht verbringen möchten.
  6. Behalten Sie die Anzahl der Bilder in einem Artikel niedrig. Häufig ist es eine gute Methode, einen Gesamtfoto eines Tools zu erstellen, das alles zeigt, und dann den Rest im Text beschreiben. Dies erleichtert das Ersetzen des Screenshots bei Bedarf.

Einige andere 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 viel davon abzuweichen. Die Breite von 800 Pixeln sollte maximal sein.
  • Verwenden Sie PNGs für Screenshots der Benutzeroberfläche.
  • Verwenden Sie PNGs oder JPGs für Screenshots des 3D-Viewports. Bevorzugen Sie qualität gegenüber komprimierungsverhältnis.

Liste der Komponenteneigenschaften

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

Vergessen Sie auch nicht, alle Sätze mit einem Punkt abzuschließen.

Prüfliste zum Seitenabschluss

  1. Stellen Sie sicher, dass die Richtlinien dieses Dokuments befolgt wurden.
  2. Durchsuchen Sie die Dokumentstruktur, und sehen Sie, ob das neue Dokument im Abschnitt "Siehe auch " anderer Seiten erwähnt werden könnte.
  3. Falls verfügbar, können Sie jemanden mit Kenntnissen über das Thema lesen, um die technische Korrektheit zu erhalten.
  4. Sie können die Seite für Formatvorlagen und Formatierungen korrekturlesen. Dies kann jemand sein, der mit dem Thema nicht vertraut ist, was auch eine gute Idee ist, feedback zu erhalten, wie verständlich die Dokumentation ist.

Quelldokumentation

API-Dokumentation wird automatisch aus den MRTK-Quelldateien generiert. Um dies zu erleichtern, sind Quelldateien erforderlich, um Folgendes zu enthalten:

Zusätzlich zur obigen Version sollte der Code gut kommentiert werden, um Wartungs-, Fehlerkorrekturen und einfache Anpassungen zu ermöglichen.

Klassen-, Struktur- und Enumerationszusammenfassungsblöcke

Wenn der MRTK eine Klasse, eine Struktur oder eine Enumeration hinzugefügt wird, muss der Zweck beschrieben werden. Dies ist die Form eines Sammelblocks über der Klasse.

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

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

/// <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-Anforderungen, die ohne Zusammenfassungen für Klassen, Strukturen oder Enumerationen übermittelt werden, werden nicht genehmigt.

Eigenschaft, Methode, Ereigniszusammenfassungsblöcke

Eigenschaften, Methoden und Ereignisse (PMEs) sowie Felder sollen mit Zusammenfassungsblöcken dokumentiert werden, unabhängig von der Codesicht (öffentlich, privat, geschützt und intern). Das Tool zur Dokumentationsgenerierung ist für das Filtern und Veröffentlichen nur der öffentlichen und geschützten Features verantwortlich.

HINWEIS: Für Unity-Methoden (z. B. "Wachen", "Start", "Aktualisieren") ist kein Sammelblock erforderlich.

PME-Dokumentation ist erforderlich , damit eine Pullanforderung genehmigt werden kann.

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>

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 Anmerkungenblock 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 Laufzeitdokumentationen für die Felder eines Skripts im Inspektor bereitzustellen.

Damit Konfigurationsoptionen in der API-Dokumentation enthalten sind, sind Skripts erforderlich, um mindestens die QuickInfoinhalte in einen Zusammenfassungsblock einzuschließen.

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

Enumerationswerte

Bei der Definition und Aufzählung muss der Code auch die Bedeutung der Enumerationswerte mithilfe eines Zusammenfassungsblocks dokumentieren. Hinweiseblöcke können optional verwendet werden, um zusätzliche Details zur Verbesserung des Verständnisses bereitzustellen.

/// <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 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 ziemlich hoher Ebene beschreiben, was bereitgestellt wird. Je nach Größe und/oder Komplexität eines bestimmten Featurebereichs kann es einen Bedarf an zusätzlichen Dateien geben, bis zu einer pro Feature bereitgestellt.

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

Im Rahmen dieser Dokumentation sollten Anleitungen, einschließlich Illustrationen, bereitgestellt werden, um Kunden beim Einstieg in ein Feature oder Konzept zu unterstützen.

Entwurfsdokumentation

Mixed Reality bietet die Möglichkeit, völlig neue Welten zu schaffen. Teil dieses Vorgangs ist wahrscheinlich die Erstellung von benutzerdefinierten Ressourcen für die Verwendung mit dem MRTK. Um dies so reibungsfrei wie möglich für Kunden zu gestalten, sollten Komponenten Entwurfsdokumentationen bereitstellen, die alle Formatierungen oder sonstigen 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 als Teil einer Pull-Anforderungsüberprüfung angefordert werden.

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

Leistungsnotizen

Einige wichtige Features kommen zu leistungsrelevanten Kosten. Dieser Code wird oft sehr abhängig davon, 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.

Leistungsnotizen werden für CPU- und/oder GPU-schwere Komponenten empfohlen und können als Teil einer Pull-Anforderungsüberprüfung angefordert werden. Alle anwendbaren Leistungsnotizen sind in der API - und Übersichtsdokumentation enthalten.

Aktuelle Änderungen

Die Dokumentation zu Änderungen wird durch eine Datei auf oberster Ebene erstellt, die mit den einzelnen breaking-changes.md des jeweiligen Featurebereichs verknüpft ist.

Der Featurebereich breaking-changes.md Dateien enthält die Liste aller bekannten Unterbrechungsänderungen für eine bestimmte Version sowie den Verlauf der Unterbrechung von Änderungen aus früheren Versionen.

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 enthaltenen Informationen breaking-changes.md Dateien werden in den Versionshinweisen für jede neue MRTK-Version aggregiert.

Alle unterbrechungsweisen Änderungen, die Teil einer Änderung sind, müssen als Teil einer Pullanforderung dokumentiert werden.

Tools zum Bearbeiten von MarkDown

Visual Studio Code ist ein großartiges Tool zum Bearbeiten von Markdowndateien, die Teil der Dokumentation von MRTK sind.

Beim Schreiben der Dokumentation wird auch die Installation der folgenden beiden Erweiterungen dringend empfohlen:

  • Docs Markdown Extension 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 veröffentlichten Dokumenterstellungspaket von Microsoft verpackt.

Siehe auch