Documentatierichtlijnen

MRTK

Dit document bevat een overzicht van de documentatierichtlijnen en -standaarden voor de Mixed Reality Toolkit (MRTK). Dit biedt een inleiding tot 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, daarom wordt de beoogde stijl en de meest voorkomende opmaakfuncties van de documentatie gebruikt.


Functionaliteit en markeringen

In deze sectie worden vaak benodigde 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; Parseren zorgt ervoor dat het juiste itemnummer wordt ingesteld.
  • Lijsten met opsommingstekens
    • Geneste lijsten met opsommingstekens
  • Tekst vetgedrukt met **dubbel sterretje**
  • cursievetekst met _onderstrepingsteken_ of *enkel sterretje*
  • Tekst highlighted as code binnen een zin 'backquotes gebruiken'
  • Koppelingen naar mrtK-documentatierichtlijnen voor docs-pagina's
  • 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 backticks '' en geven we csharp op als de taal voor syntaxismarkering:

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

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

Todos

Vermijd het gebruik van TODOs in documenten, omdat deze TODOs in de loop van de tijd (zoals code-TODO's) doorgaans verzamelen en informatie 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 takenlijst en geef voldoende achtergrond op die een andere inzender zou kunnen begrijpen en vervolgens de todo kunnen aanpakken.
  2. Verwijs naar de URL van het probleem in de taken 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 naar de lezer wilt markeren, gebruikt u > [! OPMERKING] , > [! WAARSCHUWING] en > [! BELANGRIJK] om de volgende stijlen te produceren. Het wordt aanbevolen notities te gebruiken voor algemene punten en waarschuwingspunten/belangrijke punten alleen 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 hoofdhoofdhoofdstuk moet fungeren als een korte inleiding waar het hoofdstuk over gaat. Maak dit niet te lang, voeg in plaats daarvan subkoppen toe. Hiermee kunt u koppelingen maken naar secties en deze kunnen als bladwijzers worden opgeslagen.

Hoofdtekst

Gebruik koppen op twee niveaus en drie niveaus om de rest te structureren.

Minisecties

Gebruik een vetgedrukte tekstregel voor blokken die opvallen. We kunnen dit op een bepaald moment vervangen door kopteksten op 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 waar nodig 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 mogen niet worden opgenomen in de lijst Zie ook . Zie het hoofdstuk 'Zie ook' van deze pagina als voorbeeld voor de keuze van koppelingen.

Inhoudsopgave (Inhoudsopgave)

Toc-bestanden worden gebruikt voor het genereren van de navigatiebalken in de MRTK-github.io documentatie. Wanneer er een nieuw documentatiebestand wordt toegevoegd, moet u ervoor zorgen dat er een vermelding is voor dat bestand 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 documentatie voor ontwikkelaars. Er kan een inhoudsbestand zijn voor elke submap in de documentatiemap die kan worden gekoppeld aan een bestaand inhoudsbestand 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 voorkomen. Probeer ook hyperbole en sensationeelisme te vermijden.

  1. Probeer niet te grappig te zijn.
  2. Schrijf nooit 'I'
  3. Vermijd 'we'. Dit kan meestal eenvoudig worden herformuleerd met behulp van 'MRTK' in plaats daarvan. Voorbeeld: "we ondersteunen deze functie" -> "MRTK ondersteunt deze functie" of "de volgende functies worden ondersteund ...".
  4. Probeer ook '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 dat je te enthousiast klinkt, we hoeven niets te verkopen.
  7. Vermijd ook te veel dramatisch te zijn. Uitroeptekens zijn zelden nodig.

Hoofdlettergebruik

  • Gebruik zinsvoorbeeld voor koppen. Ie. zet de eerste letter en namen in hoofdletters, maar niets anders.
  • Gebruik regelmatig Engels voor alles anders. Dat betekent dat willekeurige woorden niet hoofdletters bevatten, zelfs niet als ze een speciale betekenis in die context hebben. Geef de voorkeur aan cursieve tekst voor het markeren van bepaalde woorden, zie hieronder.
  • Wanneer een koppeling wordt ingesloten in een zin (wat de voorkeursmethode is), gebruikt de standaardhoofdhoofdletters altijd hoofdletters, waardoor de regel van geen willekeurig hoofdlettergebruik in tekst wordt verbroken. Gebruik daarom een aangepaste koppelingsnaam om het hoofdlettergebruik te herstellen. Hier volgt een koppeling naar de documentatie voor begrenzesbeheer .
  • Namen met hoofdletters, zoals Unity.
  • Gebruik geen hoofdletters voor 'editor' bij het schrijven van unity-editor.

Nadruk en markering

Er zijn twee manieren om woorden te benadrukken of te markeren, zodat ze vet worden of cursief worden. Het effect van vetgedrukte tekst is dat vetgedrukte tekst eruit blijft en daarom gemakkelijk kan worden opgemerkt tijdens het overslaan van een stuk tekst of zelfs gewoon over een pagina schuiven. Vet is geweldig om zinnen te markeren die mensen moeten onthouden. Gebruik echter zelden vetgedrukte tekst, omdat deze over het algemeen afleidend 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.

Op dezelfde manier, wanneer een bestandsnaam, een pad of een menu-item wordt vermeld in tekst, geeft u er de voorkeur aan cursief te maken om deze logisch te groeperen, zonder afgeleid te zijn.

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

Vermeldingen in menu's

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

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

Voorkeurskoppelingen die zijn ingesloten in een zin:

Vermijd externe koppelingen, ze kunnen verouderd raken of copyright-inhoud bevatten.

Als u een koppeling toevoegt, kunt 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/schermopnamen

Gebruik schermafbeeldingen spaarzaam. Het onderhouden van afbeeldingen in documentatie is veel werk, kleine wijzigingen in de gebruikersinterface kunnen veel schermopnamen maken die verouderd zijn. Met de volgende regels wordt het onderhoud verminderd:

  1. Gebruik geen schermopnamen voor dingen die in tekst kunnen worden beschreven. Vooral, maak nooit een schermopname van een eigenschappenraster voor het enige doel van het weergeven van eigenschapsnamen en -waarden.
  2. Neem geen items op in een schermopname die niet relevant zijn voor wat wordt weergegeven. Wanneer er bijvoorbeeld een renderingeffect wordt weergegeven, maakt u een schermopname van de viewport, maar sluit u een gebruikersinterface eromheen uit. Als u een bepaalde gebruikersinterface weergeeft, probeert u vensters te verplaatsen, zodat alleen dat belangrijke onderdeel zich in de afbeelding bevindt.
  3. Wanneer u de gebruikersinterface voor schermopnamen opgeeft, worden alleen de belangrijke onderdelen weergegeven. Als u bijvoorbeeld over knoppen in een werkbalk praat, maakt u een kleine afbeelding met de belangrijke werkbalkknoppen, maar sluit alles eromheen uit.
  4. Gebruik alleen afbeeldingen die eenvoudig te reproduceren zijn. Dit betekent dat u geen markeringen of markeringen in schermopnamen kunt tekenen. Ten eerste zijn er geen consistente regels hoe deze eruit moeten zien, hoe dan ook. Ten tweede is het reproduceren van een dergelijke schermopname extra moeite. Beschrijf in plaats daarvan de belangrijke onderdelen in tekst. Er zijn uitzonderingen op deze regel, maar ze zijn zeldzaam.
  5. Uiteraard is het veel meer moeite om een GIF-animatie opnieuw te maken. Verwacht dat u verantwoordelijk bent 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 te maken van een hulpprogramma, dat alles weergeeft en vervolgens de rest in tekst beschrijft. Hierdoor kunt u de schermopname eenvoudig vervangen wanneer dat nodig is.

Enkele andere aspecten:

  • De gebruikersinterface van de editor voor schermopnamen moet de editor voor lichtgrijs thema gebruiken, omdat niet alle gebruikers toegang hebben tot het donkere thema en we willen dingen zo consistent mogelijk houden.
  • De standaardafbeeldingsbreedte 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 JPG's voor 3D viewport-schermopnamen. Geef de voorkeur aan kwaliteit boven de 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 reguliere tekst om deze te beschrijven. Gebruik geen subhoofdstukken of lijsten met opsommingstekens.

Vergeet ook niet alle zinnen met een punt te voltooien.

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. Indien beschikbaar, moet 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 worden gecommentarieerd om onderhoud, bugfixes en aanpassingsgemak mogelijk te maken.

Klasse- en struct-, opsommingssamenvattingsblokken

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

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

Als er afhankelijkheden op klasseniveau zijn, moeten ze 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 zonder samenvattingen voor klassen, structuren of opsommingen worden niet goedgekeurd.

Eigenschap, 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 voor een pull-aanvraag die moet worden goedgekeurd.

Als onderdeel van een PME-samenvattingsblok is 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 en afhankelijkheden van functies

Als onderdeel van de API-overzichtsdocumentatie 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.

Zodat configuratieopties zijn opgenomen in de API-documentatie, zijn scripts vereist om ten minste de inhoud van knopinfo in een samenvattingsblok op te nemen.

/// <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 opsommingswaarden documenteren met behulp van een samenvattingsblok. Opmerkingenblokken kunnen eventueel worden gebruikt om aanvullende informatie te bieden om het begrip te verbeteren.

/// <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 de Mixed Reality Toolkit hoeven mogelijk geen gebruik te maken van de API-documentatie. Deze gebruikers maken gebruik 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 functie.

Wanneer een functie wordt toegevoegd (of het gebruik wordt gewijzigd), moet u overzichtsdocumentatie opgeven.

Als onderdeel van deze documentatie moeten secties, inclusief illustraties, worden gegeven om klanten te helpen bij het maken van een functie of concept bij het aan de slag gaan.

Ontwerpdocumentatie

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

Enkele voorbeelden waarbij ontwerpdocumentatie nuttig kan zijn:

  • Cursormodellen
  • Visualisaties voor ruimtelijke toewijzing
  • Geluidseffectbestanden

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

Dit kan wel of niet afwijken van de ontwerpaanbieding op de MS Developer-site

Prestatienotities

Sommige belangrijke functies hebben een prestatiekosten. Vaak is deze code afhankelijk van hoe deze 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 zware CPU- en/of GPU-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 over belangrijke wijzigingen bestaat uit een bestand op het hoogste niveau dat is gekoppeld aan de afzonderlijke breaking-changes.md van elk onderdeelgebied.

Het onderdeelgebied breaking-changes.md bestanden moeten de lijst bevatten met alle bekende belangrijke wijzigingen voor een bepaalde release , evenals de geschiedenis van belangrijke wijzigingen uit 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 in het functieniveau breaking-changes.md bestanden worden geaggregeerd in 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 hulpmiddel voor het bewerken van Markdown-bestanden die deel uitmaken van de documentatie van MRTK.

Bij het schrijven van documentatie 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 documentcreatieopties weer te geven.

  • Spellingcontrole voor code: 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