Richtlijnen voor documentatie

MRTK

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

De pagina zelf moet als voorbeeld fungeren en maakt daarom gebruik van de beoogde stijl en de meest voorkomende markeringsfuncties van de documentatie.


Functionaliteit en markeringen

In deze sectie worden veelgebruikte functies beschreven. Bekijk de broncode van de pagina om te zien hoe ze werken.

  1. Genummerde lijsten
    1. Geneste genummerde lijsten met ten minste drie vooraanstaande spaties
    2. Het werkelijke getal in de code is niet relevant; Parseren zorgt voor het instellen van het juiste itemnummer.
  • Lijsten met opsommingstekens
    • Lijsten met geneste opsommingstekens
  • Vetgedrukte tekst * * met dubbel sterretje**
  • italic text with underscore or single asterisk (italic text with underscore or single asterisk )Italic text with _ underscore or _ single * asterisk*
  • Tekst highlighted as code in een zin met behulp van ` backquotes`
  • 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 het markeren van syntaxis:

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

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

Todos

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

Als het absoluut noodzakelijk is om een todo toe te voegen, volgt u deze stappen:

  1. Een nieuw probleem indienen op Github met een beschrijving van de context achter de todo en voldoende achtergrondinformatie bieden die een andere inzender kan begrijpen en vervolgens kan oplossen.
  2. Verwijs naar de URL van het probleem in de todo in de documenten.

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: A brief blurb on the issue -->

Gemarkeerde secties

Als u specifieke punten voor de lezer wilt markeren, gebruikt > [!NOTE] u , en om de volgende stijlen te > [!WARNING] > [!IMPORTANT] produceren. Het is raadzaam om alleen voor speciale relevante gevallen notities te gebruiken voor algemene punten en waarschuwings-/belangrijke punten.

Notitie

Voorbeeld van een opmerking

Waarschuwing

Voorbeeld van een waarschuwing

Belangrijk

Voorbeeld van een belangrijke opmerking

Pagina-indeling

Introductie

Het deel direct na de hoofdtitel van het hoofdstuk moet fungeren als een korte inleiding waar het hoofdstuk over gaat. Maak dit niet te lang, maar voeg subkoppen toe. Deze kunnen worden gekoppeld aan secties en kunnen worden opgeslagen als bladwijzers.

Hoofd hoofd

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

Mini-secties

Gebruik een vetgedrukte tekstregel voor blokken die moeten opvallen. We kunnen dit op een bepaald moment vervangen door koppen van vier niveau.

De sectie 'Zie ook'

De meeste pagina's moeten eindigen met een hoofdstuk met de naam Zie ook. Dit hoofdstuk is gewoon een opsomming met koppelingen naar pagina's met betrekking tot dit onderwerp. Deze koppelingen kunnen waar nodig ook worden weergegeven in de paginatekst, maar dit is niet vereist. Op dezelfde manier kan de paginatekst koppelingen bevatten naar pagina's die niet gerelateerd zijn 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

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 voor dat bestand staat in een van de toc.yml-bestanden van de map met documentatie. Alleen artikelen die in de toc-bestanden worden vermeld, worden weergegeven in de navigatie van de ontwikkelaars docs. Er kan een toc-bestand zijn voor elke submap in de documentatiemap die kan worden gekoppeld aan een bestaand toc-bestand om het toe te voegen als een subsectie aan het bijbehorende deel van de navigatie.

Stijl

Schrijfstijl

Algemene vuistregel: Probeer professioneel te klinken. Dit betekent meestal om een 'gesprekstoon' te voorkomen. Probeer ook hyperbolische en gevoelsgevoeligheid te voorkomen.

  1. Probeer niet (te veel) te doen.
  2. Schrijf nooit 'I'
  3. Vermijd 'we'. Dit kan meestal eenvoudig worden geformuleerd met behulp van MRTK. 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 'diskettes'.
  6. Vermijd al te enthousiast te klinken, we hoeven niets te verkopen.
  7. Op dezelfde manier kunt u voorkomen dat u te ingrijpend te werk gaat. Uitroeptekens zijn zelden nodig.

Hoofdlettergebruik

  • Gebruik Zinscase voor koppen. Bijvoorbeeld: hoofdletters voor de eerste letter en namen, maar niets anders.
  • Gebruik normaal Engels voor al het andere. Dit betekent dat u geen willekeurige woorden in hoofdletters moet zetten, zelfs niet als ze een speciale betekenis hebben in die context. Geef de voorkeur aan italische tekst voor het markeren van bepaalde woorden. Zie hieronder.
  • Wanneer een koppeling is ingesloten in een zin (dit is de voorkeursmethode), gebruikt de standaardnaam van het hoofdstuk altijd hoofdletters, waardoor de regel van geen willekeurig hoofdlettergebruik in tekst wordt doorbreekt. Gebruik daarom een aangepaste koppelingsnaam om het hoofdlettergebruik te herstellen. Hier is een voorbeeld van een koppeling naar de documentatie voor besturingselementen voor grenzen.
  • Maak hoofdletters van namen, zoals Unity.
  • Schrijf 'editor' NIET in hoofdletters bij het schrijven van de Unity-editor.

Nadruk en markering

Er zijn twee manieren om woorden te benadrukken of te markeren, door ze vet of italisch te maken. Het effect van vetgedrukte tekst is dat vetgedrukte tekst wordt weergegeven en daarom eenvoudig kan worden opgemerkt tijdens het overslaan van een stukje tekst of zelfs gewoon schuiven over een pagina. Vet is geweldig om zinnen te markeren die mensen moeten onthouden. Gebruik echter zelden vetgedrukte tekst, omdat deze doorgaans storend is.

Vaak wil iemand iets 'groepeer' dat logisch bij elkaar hoort of een specifieke term markeren, omdat deze een speciale betekenis heeft. Dergelijke zaken hoeven niet op te vallen in de algehele tekst. Gebruik italische tekst als een lichtgewicht methode om iets te markeren.

Wanneer een bestandsnaam, een pad of een menu-vermelding wordt vermeld in tekst, geeft u er ook de voorkeur aan italic te maken om deze logisch te groeperen, zonder storend te zijn.

Probeer over het algemeen onnodige tekst markeren te voorkomen. Speciale termen kunnen eenmaal worden gemarkeerd om de lezer bewust te maken. Herhaal dergelijke markeringen niet overal in de tekst, wanneer deze geen doel meer heeft en alleen storend is.

Vermeldingen in het menu vermelden

Bij het vermelden van een menu-vermelding 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 één keer. Stel dat een lezer op elke koppeling op de pagina klikt en denkt na over hoe vervelend het zou zijn als dezelfde pagina 20 keer wordt geopend.

Geef de voorkeur aan koppelingen die zijn ingesloten in een zin:

Vermijd externe koppelingen, ze kunnen verouderd raken of auteursrechtelijk beschermd inhoud bevatten.

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

Afbeeldingen/schermopnamen

Gebruik spaarzaam schermopnamen. 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 onderhoudsinspanning:

  1. Gebruik geen schermopnamen voor dingen die in tekst kunnen worden beschreven. Maak met name nooit een schermopname van een eigenschappenraster met als enige doel eigenschapsnamen en -waarden weer te geven.
  2. Neem geen dingen op in een schermopname die niet relevant zijn voor wat er wordt weergegeven. Wanneer bijvoorbeeld een rendering-effect wordt weergegeven, maakt u een schermopname van de viewport, maar sluit u alle gebruikersinterfaces eromheen uit. Probeer met een bepaalde gebruikersinterface vensters te verplaatsen zodat alleen dat belangrijke onderdeel in de afbeelding staat.
  3. Wanneer u de gebruikersinterface van de schermopname opeendrukt, worden alleen de belangrijke onderdelen weergeven. Als u bijvoorbeeld op een werkbalk over knoppen praat, maakt u een kleine afbeelding met de belangrijke knoppen op de werkbalk, maar sluit u alles om de knop heen uit.
  4. Gebruik alleen afbeeldingen die eenvoudig kunnen worden gereproduceerd. Dit betekent dat u geen markeringen verft of markeert in schermopnamen. Ten eerste zijn er toch geen consistente regels hoe deze eruit moeten zien. Ten tweede is het reproduceren van een dergelijke schermopname een extra inspanning. Beschrijf in plaats daarvan de belangrijke onderdelen in tekst. Er zijn uitzonderingen op deze regel, maar deze zijn zeldzaam.
  5. Het is natuurlijk veel meer moeite om een GIF-animatie opnieuw te maken. U kunt ervan uit gaan dat u verantwoordelijk bent om deze opnieuw te maken tot het einde van de tijd, of dat u verwacht dat mensen het zullen uitgeven als ze die tijd niet willen besteden.
  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 weer te geven en vervolgens de rest in tekst te beschrijven. Hierdoor kunt u de schermopname eenvoudig vervangen wanneer dat nodig is.

Enkele andere aspecten:

  • In de gebruikersinterface van de editor voor schermopnamen moet een lichtgrijs thema-editor worden gebruikt, omdat niet alle gebruikers toegang hebben tot het donkere thema en we de zaken zo consistent mogelijk willen houden.
  • De standaardbreedte van de afbeelding is 500 pixels, omdat dit goed wordt weergegeven op de meeste monitors. 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 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 regelbreaks en normale tekst om ze te beschrijven. Gebruik geen subhoofdlijsten of lijsten met opsommingstekens.

Vergeet ook niet om alle zinnen te voltooien met een punt.

Controlelijst voor pagina-voltooiing

  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 in de sectie Zie ook van andere pagina's.
  3. Vraag, indien beschikbaar, iemand met kennis van het onderwerp om de pagina te lezen voor technische juistheid.
  4. Iemand de pagina laten lezen 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:

Naast het bovenstaande moet de code goed worden becommentereerd om onderhoud, foutfixes en aanpassingsgemak mogelijk te maken.

Klassen-, struct-, enum-samenvattingsblokken

Als een klasse, struct of enum wordt toegevoegd aan de MRTK, moet het doel ervan worden beschreven. Dit is om de vorm aan te nemen 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 zonder samenvattingen voor klassen, structuren of enums worden ingediend, worden niet goedgekeurd.

Eigenschap, methode, blokken met gebeurtenissamenvatting

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: Ontwaken, 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 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>

Geseraliseerde velden

Het is een goed idee om het kenmerk knopinfo van Unity te gebruiken om runtimedocumentatie te bieden voor de velden van een script in de inspector.

Om ervoor te zorgen dat configuratieopties worden opgenomen in de API-documentatie, moeten scripts ten minste de inhoud van de knopinfo opnemen in een samenvattingsblok.

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

Enumeratiewaarden

Bij het definiëren en opsnoemen moet code ook de betekenis van de opsommingswaarden documenteren met behulp van een samenvattingsblok. Opmerkingenblokken kunnen eventueel worden gebruikt om meer informatie te bieden om meer inzicht te krijgen.

/// <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 hoe u dit kunt doen

Veel gebruikers van de 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 maken.

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

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

Als onderdeel van deze documentatie moeten secties met de gebruiks how-to, inclusief illustraties, worden verstrekt om klanten te helpen die niet bekend zijn met een functie of concept om aan de slag te gaan.

Ontwerpdocumentatie

Mixed Reality biedt de mogelijkheid om volledig nieuwe werelden te maken. Een deel van dit is waarschijnlijk het maken van aangepaste assets voor gebruik met de MRTK. Om dit voor klanten zo frictieloos mogelijk te maken, moeten onderdelen ontwerpdocumentatie bieden waarin eventuele opmaak of andere vereisten voor art assets worden beschreven.

Enkele voorbeelden waarin ontwerpdocumentatie nuttig kan zijn:

  • Cursormodellen
  • Visualisaties voor ruimtelijke toewijzing
  • Geluidseffectbestanden

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

Dit kan al dan niet verschillen van de ontwerpaanbeveling op de MS Developer-site

Opmerkingen bij de prestaties

Sommige belangrijke functies hebben prestatiekosten. Vaak is deze code erg 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.

Prestatienotities worden aanbevolen voor cpu- en/of GPU-zware onderdelen en kunnen worden aangevraagd als onderdeel van een pull-aanvraagbeoordeling. Eventuele toepasselijke prestatienotities 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 koppelingen naar de afzonderlijke functies van elk breaking-changes.md.

Het functiegebied breaking-changes.md bestanden bevat de lijst 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 die is opgenomen in het functieniveau breaking-changes.md bestanden worden geaggregeerd in de releasenotities voor elke nieuwe MRTK-release.

Eventuele belangrijke wijzigingen 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 geweldig hulpprogramma voor het bewerken van Markdown-bestanden die deel uitmaken van de MRTK-documentatie.

Bij het schrijven van documentatie wordt ook het installeren van de volgende twee extensies ten zeerste aanbevolen:

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

  • Code Spell Checker: 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