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 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 markeringsfuncties van de documentatie gebruikt.

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; Parseren zorgt ervoor dat het juiste itemnummer wordt ingesteld.
  • Lijsten met opsommingstekens
    • Geneste lijsten met opsommingstekens
  • Tekst vetgedrukt met **dubbel sterretje**
  • cursieve tekst met _onderstrepingsteken_ of *enkel sterretje*
  • Tekst highlighted as code binnen een zin 'met backquotes'
  • Koppelingen naar documentatierichtlijnen voor MRTK-documentatie voor docs-pagina's
  • Koppelingen naar ankers op 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.

TODO's

Vermijd het gebruik van TODO's in documenten, omdat deze TODO's in de loop van de tijd (zoals code-TODO's) meestal worden verzameld 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 in op Github waarin de context achter de takenlijst wordt beschreven en geef voldoende achtergrond op die een andere inzender zou kunnen begrijpen en vervolgens de todo kunnen oplossen.
  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 waarschuwing/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

Inleiding

Het deel direct na de titel van het hoofdhoofdstuk dient als korte inleiding waar het hoofdstuk over gaat. Maak dit niet te lang, voeg in plaats daarvan subkoppen toe. Hiermee kunt u een koppeling maken naar secties en deze kunnen worden opgeslagen als bladwijzers.

Hoofdtekst

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

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 koppelingen naar pagina's die betrekking hebben op dit onderwerp. Deze koppelingen kunnen ook worden weergegeven in de paginatekst, indien van toepassing, 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 voor dat bestand in een van de toc.yml bestanden van de documentatiemap staat. Alleen artikelen die in de inhoudsbestanden worden vermeld, worden weergegeven in de navigatie van de ontwikkelaarsdocumenten. Er kan een inhoudsbestand zijn voor elke submap in de documentatiemap die kan worden gekoppeld aan een bestaand toc-bestand om het toe te voegen als subsectie 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 'Ik'
  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 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. Voorkom dat u overvallend enthousiast klinkt, we hoeven niets te verkopen.
  7. Vermijd op dezelfde manier te veel dramatisch te zijn. Uitroeptekens zijn zelden nodig.

Hoofdlettergebruik

  • Gebruik zinsvoorbeeld voor koppen. Ie. hoofdletters maken van de eerste letter en namen, maar niets anders.
  • Gebruik regelmatig Engels voor al het andere. Dat betekent dat willekeurige woorden niet hoofdletters bevatten, zelfs 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 is ingesloten in een zin (de voorkeursmethode), gebruikt de standaardhoofdletters altijd hoofdletters, waardoor de regel van geen willekeurig hoofdlettergebruik in tekst wordt onderbroken. Gebruik daarom een aangepaste koppelingsnaam om het hoofdlettergebruik te herstellen. Hier volgt een koppeling naar de documentatie voor begrenzesbeheer .
  • Gebruik hoofdletternamen, 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.

Als een bestandsnaam, pad of menu-item wordt vermeld in tekst, geeft u er ook de voorkeur aan cursief te maken om deze logisch te groeperen, zonder dat u afgeleid hoeft te zijn.

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

Vermeldingen in het menu Vermelden

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

Voeg zo veel 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 nadenkt over hoe vervelend het zou zijn, als dezelfde pagina 20 keer wordt geopend.

De voorkeur geven aan koppelingen die zijn ingesloten in een zin:

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

Wanneer u een koppeling toevoegt, moet u overwegen of deze ook moet worden vermeld in de sectie Zie ook . Controleer op dezelfde manier of er 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 veel schermafbeeldingen maken die verouderd zijn. Met de volgende regels wordt het onderhoud verminderd:

  1. Gebruik geen schermopnamen voor dingen die in tekst kunnen worden beschreven. 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. Als er bijvoorbeeld een weergave-effect wordt weergegeven, maakt u een schermopname van de viewport, maar sluit u een ui eromheen uit. Als u een aantal gebruikersinterfaces weergeeft, probeert u vensters zodanig te verplaatsen dat 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 u alles eromheen uit.
  4. Gebruik alleen afbeeldingen die eenvoudig te reproduceren zijn. Dat betekent dat u geen verfmarkeringen of markeringen in schermopnamen hoeft te maken. 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 de tekst. Er zijn uitzonderingen op deze regel, maar ze zijn zeldzaam.
  5. Het is natuurlijk 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 van een hulpprogramma te maken, 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 lichtgrijs thema-editor 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. De voorkeur geven 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, vervolgens regeleinden en gewone tekst om deze te beschrijven. Gebruik geen subhoofdhoofdstukken of lijsten met opsommingstekens.

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

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 voor stijl en opmaak controleren. 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 te vergemakkelijken, moeten bronbestanden het volgende bevatten:

Naast het bovenstaande moet de code goed worden gecommentarieerd om onderhoud, bugfixes en aanpassingen mogelijk te maken.

Class, struct, enum summary blocks

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 die worden ingediend 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 overzichtsblokken, 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 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>

Versie en afhankelijkheden van de introductie 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 uitbreidings- 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 de knopinfo in een overzichtsblok 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 enumwaarden 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 voor procedures

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

Elk functiegebied bevat een of meer Markdown-bestanden (.md) die op een redelijk hoog niveau beschrijven, wat wordt geleverd. 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 er overzichtsdocumentatie worden opgegeven.

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

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 MRTK. Om dit zo wrijvingsvrij mogelijk te maken voor klanten, moeten onderdelen ontwerpdocumentatie bieden waarin de 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 ontwerpaanveling op de MS Developer-site

Prestatienotities

Sommige belangrijke functies hebben een prestatiekosten. Deze code is vaak erg afhankelijk van hoe deze zijn geconfigureerd.

Voorbeeld:

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 beoordeling van een pull-aanvraag. 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 functiegebied.

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

Voorbeeld:

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.

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 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 ontwerpopties voor documenten 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