Delen via

Documentatierichtlijnen — MRTK2

  • Artikel
MRTK

Dit document bevat een overzicht van de documentatierichtlijnen en -standaarden voor Mixed Reality Toolkit (MRTK). Dit biedt een inleiding tot de technische aspecten van het schrijven en genereren van documentatie, om veelvoorkomende valkuilen te benadrukken en de aanbevolen schrijfstijl te beschrijven.

De pagina zelf moet als voorbeeld dienen en gebruikt daarom de beoogde stijl en de meest voorkomende markeringsfuncties van de documentatie.

Functionaliteit en markeringen

In deze sectie worden veelgebruikte functies beschreven. Als u wilt zien hoe ze werken, bekijkt u de broncode van de pagina.

  1. Genummerde lijsten
    1. Geneste genummerde lijsten met ten minste 3 voorloopspaties
    2. Het werkelijke getal in code is niet relevant; Bij het parseren wordt het juiste itemnummer ingesteld.
  • Lijsten met opsommingstekens
    • Geneste lijsten met opsommingstekens
  • Tekst vet met **dubbel sterretje**
  • cursievetekst met _onderstrepingsteken_ of *één sterretje*
  • Tekst highlighted as code binnen een zin 'met backquotes'
  • Koppelingen naar documentatiepagina's mrtk-documentatierichtlijnen
  • Koppelingen naar ankers binnen een pagina; ankers worden gevormd door spaties te vervangen door streepjes en te converteren naar kleine letters

Voor codevoorbeelden gebruiken we de blokken met drie accenten en geven we csharp op als de taal voor syntaxismarkering:

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

Bij het vermelden van code in een zin use a single backtick.

Todos

Vermijd het gebruik van TOPO's in documenten, omdat deze TODO's (zoals code-TODO's) na verloop van tijd vaak informatie verzamelen over hoe ze moeten worden bijgewerkt en waarom ze verloren gaan.

Als het absoluut noodzakelijk is om een todo toe te voegen, voert u de volgende stappen uit:

  1. Dien een nieuw probleem op Github in met een beschrijving van de context achter de todo en geef voldoende achtergrondinformatie op die een andere inzender kan begrijpen en vervolgens de toDO kan aanpakken.
  2. Verwijs naar de URL van het probleem in de todo in de documenten.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: een korte blurb over het probleem -->

Gemarkeerde secties

Als u specifieke punten voor de lezer wilt markeren, gebruikt u > [! OPMERKING] , > [! WAARSCHUWING] , en > [! BELANGRIJK] om de volgende stijlen te produceren. Het wordt aanbevolen om notities alleen te gebruiken voor algemene punten en waarschuwings-/belangrijke punten voor speciale relevante gevallen.

Notitie

Voorbeeld van een notitie

Waarschuwing

Voorbeeld van een waarschuwing

Belangrijk

Voorbeeld van een belangrijke opmerking

Pagina-indeling

Introductie

Het deel direct na de titel van het hoofdhoofdstuk moet dienen als een korte inleiding waar het hoofdstuk over gaat. Maak dit niet te lang, voeg in plaats daarvan subkoppen toe. Deze maken het mogelijk om een koppeling naar secties te maken en kunnen worden opgeslagen als bladwijzers.

Hoofdtekst

Gebruik kopteksten met twee en drie niveaus om de rest te structureren.

Minisecties

Gebruik een vetgedrukte tekstregel voor blokken die moeten opvallen. We kunnen dit op een gegeven moment vervangen door koppen met vier niveaus.

Sectie 'Zie ook'

De meeste pagina's moeten eindigen met een hoofdstuk met de naam Zie ook. Dit hoofdstuk is gewoon een lijst met opsommingstekens met koppelingen naar pagina's die betrekking hebben op dit onderwerp. Deze koppelingen kunnen indien van toepassing ook in de paginatekst worden weergegeven, maar dit is niet vereist. Op dezelfde manier kan de paginatekst koppelingen bevatten naar pagina's die niet zijn gerelateerd aan het hoofdonderwerp. Deze moeten niet worden opgenomen in de lijst Zie ook . Zie het hoofdstuk 'Zie ook' van deze pagina als voorbeeld voor de keuze van koppelingen.

Inhoudsopgave

Toc-bestanden worden gebruikt voor het genereren van de navigatiebalken in de MRTK github.io documentatie. Wanneer een nieuw documentatiebestand wordt toegevoegd, moet u ervoor zorgen dat er een vermelding voor dat bestand is in een van de toc.yml-bestanden van de documentatiemap. Alleen artikelen die in de toc-bestanden worden vermeld, worden weergegeven in de navigatie van de ontwikkelaarsdocumenten. Er kan een toc-bestand zijn voor elke submap in de documentatiemap die kan worden gekoppeld aan een bestaand toc-bestand om het als subsectie toe te voegen aan het bijbehorende deel van de navigatie.

Stijl

Schrijfstijl

Algemene vuistregel: Probeer professioneel te klinken. Dat betekent meestal om een 'gesprekstoon' te vermijden. Probeer ook hyperbole en sensationalisme te vermijden.

  1. Probeer niet te grappig te zijn.
  2. Schrijf nooit 'ik'
  3. Vermijd 'we'. Dit kan meestal eenvoudig opnieuw worden geformuleerd, met behulp van 'MRTK' in plaats daarvan. Voorbeeld: 'we ondersteunen deze functie' -> 'MRTK ondersteunt deze functie' of 'de volgende functies worden ondersteund...'.
  4. Probeer op dezelfde manier 'u' te vermijden. Voorbeeld: 'Met deze eenvoudige wijziging wordt uw shader configureerbaar!' -> 'Shaders kunnen met weinig moeite worden geconfigureerd'.
  5. Gebruik geen 'slordige woordgroepen'.
  6. Vermijd oversprikkeld te klinken, we hoeven niets te verkopen.
  7. Vermijd ook te dramatisch te zijn. Uitroeptekens zijn zelden nodig.

Hoofdlettergebruik

  • Gebruik Zinsvoorbeeld voor koppen. Ie. geef de eerste letter en namen een hoofdletter, maar niets anders.
  • Gebruik gewoon Engels voor al het andere. Dat betekent dat willekeurige woorden niet met hoofdletters moeten worden gekapitaliseerd, zelfs als ze een speciale betekenis hebben in die context. Geef de voorkeur aan cursieve tekst voor het markeren van bepaalde woorden, zie hieronder.
  • Wanneer een koppeling is ingesloten in een zin (wat de voorkeursmethode is), gebruikt de standaardhoofdstuknaam altijd hoofdletters, waardoor de regel van geen willekeurige hoofdletters in tekst wordt verbroken. Gebruik daarom een aangepaste koppelingsnaam om het hoofdlettergebruik te herstellen. Hier volgt een voorbeeld van een koppeling naar de documentatie voor het besturingselement voor grenzen .
  • Gebruik namen met hoofdletters, zoals Unity.
  • Gebruik 'editor' NIET met hoofdletters bij het schrijven van unity-editor.

Nadruk en markering

Er zijn twee manieren om woorden te benadrukken of te markeren: vet of cursief maken. Het effect van vetgedrukte tekst is dat vetgedrukte tekst opvalt en daarom gemakkelijk kan worden opgemerkt tijdens het overslaan van een stuk tekst of zelfs het schuiven over een pagina. Vet is geweldig om woordgroepen te markeren die mensen moeten onthouden. Gebruik echter zelden vetgedrukte tekst, omdat deze over het algemeen storend is.

Vaak wil men iets 'groeperen' dat logisch bij elkaar hoort of een specifieke term markeren, omdat het een speciale betekenis heeft. Dergelijke dingen hoeven niet op te vallen in de algemene tekst. Gebruik cursieve tekst als een lichtgewicht methode om iets te markeren.

En wanneer een bestandsnaam, een pad of een menu-item in tekst wordt vermeld, geeft u er de voorkeur aan om het cursief te maken om deze logisch te groeperen, zonder af te leiden.

Probeer over het algemeen onnodige tekstmarkeringen te voorkomen. Speciale termen kunnen eenmaal worden gemarkeerd om de lezer bewust te maken, herhaal dergelijke markeringen niet in de hele tekst, wanneer het geen doel meer heeft en alleen wordt afgeleid.

Vermelding van menu-items

Wanneer u een menu-item vermeldt waarop een gebruiker moet klikken, is de huidige conventie: Project > Files > Create > Leaf

Voeg zoveel mogelijk nuttige koppelingen naar andere pagina's in, maar elke koppeling slechts eenmaal. Stel dat een lezer op elke koppeling op de pagina klikt en bedenk hoe vervelend het zou zijn als dezelfde pagina 20 keer wordt geopend.

Liever koppelingen die in een zin zijn ingesloten:

Vermijd externe koppelingen, deze kunnen verouderd raken of auteursrechtelijk beschermde inhoud bevatten.

Wanneer u een koppeling toevoegt, moet u overwegen of deze ook moet worden vermeld in de sectie Zie ook . Controleer ook of een koppeling naar de nieuwe pagina moet worden toegevoegd aan de gekoppelde pagina.

Afbeeldingen/schermafbeeldingen

Gebruik schermopnamen spaarzaam. Het onderhouden van afbeeldingen in documentatie is veel werk. Kleine wijzigingen in de gebruikersinterface kunnen ervoor zorgen dat veel schermopnamen verouderd zijn. De volgende regels verminderen de onderhoudswerkzaamheden:

  1. Gebruik geen schermopnamen voor dingen die in tekst kunnen worden beschreven. Maak vooral nooit een schermopname van een eigenschappenraster met als enig doel de namen en waarden van eigenschappen weer te geven.
  2. Neem geen dingen op in een schermopname die niet relevant zijn voor wat wordt weergegeven. Wanneer bijvoorbeeld een rendering-effect wordt weergegeven, maakt u een schermopname van de viewport, maar sluit u de gebruikersinterface eromheen uit. Als u een bepaalde gebruikersinterface weergeeft, probeert u vensters zodanig te verplaatsen dat alleen dat belangrijke deel in de afbeelding staat.
  3. Wanneer u de gebruikersinterface voor schermopnamen opgeeft, geeft u alleen de belangrijke onderdelen weer. Als u het bijvoorbeeld hebt over knoppen in een werkbalk, maakt u een kleine afbeelding met de belangrijke werkbalkknoppen, maar sluit u alles eromheen uit.
  4. Gebruik alleen afbeeldingen die eenvoudig te reproduceren zijn. Dit betekent dat u geen markeringen of markeringen in schermopnamen overschildert. Ten eerste zijn er geen consistente regels hoe deze eruit moeten zien. Ten tweede is het reproduceren van een dergelijke schermopname extra inspanning. Beschrijf in plaats daarvan de belangrijke onderdelen in tekst. Er zijn uitzonderingen op deze regel, maar deze zijn zeldzaam.
  5. Uiteraard is het veel meer moeite om een gif-animatie opnieuw te maken. Verwacht dat u de verantwoordelijkheid hebt om het opnieuw te maken tot het einde van de tijd, of verwacht dat mensen het weggooien als ze die tijd niet willen doorbrengen.
  6. Houd het aantal afbeeldingen in een artikel laag. Vaak is het een goede methode om één algemene schermopname van een hulpprogramma te maken, waarin alles wordt weergegeven, en vervolgens de rest in tekst te beschrijven. Hierdoor kunt u de schermopname eenvoudig vervangen wanneer dat nodig is.

Enkele andere aspecten:

  • De gebruikersinterface van de editor voor schermopnamen moet gebruikmaken van de lichtgrijze thema-editor, omdat niet alle gebruikers toegang hebben tot het donkere thema en we willen alles zo consistent mogelijk houden.
  • De standaardbreedte van de afbeelding is 500 pixels, omdat dit goed wordt weergegeven op de meeste beeldschermen. Probeer er niet te veel van af te wijken. De breedte van 800 pixels moet het maximum zijn.
  • Gebruik PNG's voor schermopnamen van de gebruikersinterface.
  • Gebruik PNG's of JPEG's voor 3D-viewport-schermopnamen. Geef de voorkeur aan kwaliteit boven compressieverhouding.

Lijst met onderdeeleigenschappen

Wanneer u een lijst met eigenschappen documenteert, gebruikt u vetgedrukte tekst om de naam van de eigenschap te markeren en vervolgens regeleinden en gewone tekst om deze te beschrijven. Gebruik geen subhoofdstukken of lijsten met opsommingstekens.

Vergeet ook niet om alle zinnen af te ronden met een punt.

Controlelijst voor paginavoltooiing

  1. Zorg ervoor dat de richtlijnen van dit document zijn gevolgd.
  2. Blader door de documentstructuur en kijk of het nieuwe document kan worden vermeld onder de sectie Zie ook van andere pagina's.
  3. Laat, indien beschikbaar, iemand met kennis van het onderwerp de pagina controleren op technische juistheid.
  4. Laat iemand de pagina controleren voor stijl en opmaak. Dit kan iemand zijn die niet bekend is met het onderwerp, wat ook een goed idee is om feedback te krijgen over hoe begrijpelijk de documentatie is.

Brondocumentatie

API-documentatie wordt automatisch gegenereerd op basis van de MRTK-bronbestanden. Om dit mogelijk te maken, moeten bronbestanden het volgende bevatten:

Bovendien moet de code goed van commentaar worden voorzien om onderhoud, oplossingen voor fouten en aanpassingsgemak mogelijk te maken.

Samenvattingsblokken klasse, struct, enum

Als een klasse, struct of opsomming wordt toegevoegd aan de MRTK, moet het doel ervan worden beschreven. Dit moet de vorm hebben van een samenvattingsblok boven de klasse.

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

Als er afhankelijkheden op klasseniveau zijn, moeten deze worden gedocumenteerd in een opmerkingenblok, direct onder de samenvatting.

/// <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-aanvragen die worden ingediend zonder samenvattingen voor klassen, structuren of opsommingen, worden niet goedgekeurd.

Eigenschappen, methode, gebeurtenissamenvattingsblokken

Eigenschappen, methoden en gebeurtenissen (PME's) en velden moeten worden gedocumenteerd met samenvattingsblokken, ongeacht de zichtbaarheid van code (openbaar, privé, beveiligd en intern). Het hulpprogramma voor het genereren van documentatie is verantwoordelijk voor het filteren en publiceren van alleen de openbare en beveiligde functies.

OPMERKING: Er is geen samenvattingsblok vereist voor Unity-methoden (bijvoorbeeld: Wakker, Starten, Bijwerken).

PME-documentatie is vereist om een pull-aanvraag te kunnen goedkeuren.

Als onderdeel van een PME-samenvattingsblok zijn de betekenis en het doel van parameters en geretourneerde gegevens vereist.

/// <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>

Introductieversie van functies en afhankelijkheden

Als onderdeel van de API-samenvattingsdocumentatie moet informatie over de MRTK-versie waarin de functie is geïntroduceerd en eventuele afhankelijkheden worden gedocumenteerd in een opmerkingenblok.

Afhankelijkheden moeten extensie- en/of platformafhankelijkheden bevatten.

/// <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>

Geserialiseerde velden

Het is een goede gewoonte om het kenmerk tooltip van Unity te gebruiken om runtimedocumentatie te bieden voor de velden van een script in de inspector.

Om configuratieopties in de API-documentatie op te nemen, moeten scripts ten minste de inhoud van de knopinfo in een overzichtsblok opnemen.

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

Opsommingswaarden

Bij het definiëren en inventariseren moet code ook de betekenis van de enum-waarden documenteren met behulp van een samenvattingsblok. Opmerkingenblokken kunnen desgewenst worden gebruikt om aanvullende details te bieden om het begrip te vergroten.

/// <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>

Documentatie over procedures

Veel gebruikers van Mixed Reality Toolkit hoeven de API-documentatie mogelijk niet te gebruiken. Deze gebruikers profiteren van onze vooraf gemaakte, herbruikbare prefabs en scripts om hun ervaringen te creëren.

Elk onderdeelgebied bevat een of meer Markdown-bestanden (.md) die op een redelijk hoog niveau beschrijven wat er wordt opgegeven. Afhankelijk van de grootte en/of complexiteit van een bepaald functiegebied, is er mogelijk behoefte aan extra bestanden, maximaal één per opgegeven functie.

Wanneer een functie wordt toegevoegd (of het gebruik wordt gewijzigd), moet er overzichtsdocumentatie worden verstrekt.

Als onderdeel van deze documentatie moeten instructiesecties, inclusief illustraties, worden gegeven om klanten die nieuw zijn met een functie of concept aan de slag te helpen.

Ontwerpdocumentatie

Mixed Reality biedt een kans om geheel nieuwe werelden te creëren. Een deel hiervan omvat waarschijnlijk het maken van aangepaste assets voor gebruik met MRTK. Om dit zo probleemloos mogelijk te maken voor klanten, moeten onderdelen ontwerpdocumentatie bieden waarin eventuele opmaak of andere vereisten voor kunstassets worden beschreven.

Enkele voorbeelden waarbij ontwerpdocumentatie nuttig kan zijn:

  • Cursormodellen
  • Visualisaties van ruimtelijke toewijzingen
  • Geluidseffectbestanden

Dit type documentatie wordt sterk aanbevolen en kan worden aangevraagd als onderdeel van een beoordeling van een pull-aanvraag.

Dit kan al dan niet afwijken van de ontwerpaan aanbeveling op de MS Developer-site

Prestatieopmerkingen

Voor sommige belangrijke functies worden prestatiekosten in rekening gebracht. Deze code is vaak afhankelijk van hoe ze zijn geconfigureerd.

Bijvoorbeeld:

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.

Prestatieopmerkingen worden aanbevolen voor cpu- en/of GPU-zware onderdelen en kunnen worden aangevraagd als onderdeel van een pull-aanvraagbeoordeling. Eventuele toepasselijke prestatieopmerkingen moeten worden opgenomen in de API - en overzichtsdocumentatie.

Wijzigingen die fouten veroorzaken

Documentatie voor belangrijke wijzigingen bestaat uit een bestand op het hoogste niveau dat is gekoppeld aan de afzonderlijke breaking-changes.md van elk functiegebied.

Het functiegebied breaking-changes.md bestanden bevatten de lijst met alle bekende wijzigingen die fouten veroorzaken voor een bepaalde release , evenals de geschiedenis van wijzigingen die fouten veroorzaken in eerdere releases.

Bijvoorbeeld:

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

De informatie op het functieniveau breaking-changes.md bestanden wordt samengevoegd met de releaseopmerkingen voor elke nieuwe MRTK-release.

Wijzigingen die fouten veroorzaken die deel uitmaken van een wijziging , moeten worden gedocumenteerd als onderdeel van een pull-aanvraag.

Hulpprogramma's voor het bewerken van MarkDown

Visual Studio Code is een uitstekend hulpprogramma voor het bewerken van Markdown-bestanden die deel uitmaken van de documentatie van MRTK.

Wanneer u documentatie schrijft, wordt het installeren van de volgende twee extensies ook ten zeerste aanbevolen:

  • Docs Markdown-extensie voor Visual Studio Code: gebruik Alt+M om een menu met ontwerpopties voor docs weer te geven.

  • Code spellingcontrole - verkeerd gespelde woorden worden onderstreept; Klik met de rechtermuisknop op een verkeerd gespeld woord om het te wijzigen of op te slaan in de woordenlijst.

Beide zijn verpakt in het door Microsoft gepubliceerde Docs Authoring Pack.

Zie ook