Riktlinjer för dokumentation

MRTK

Det här dokumentet beskriver riktlinjerna för dokumentation och standarder för Mixed Reality Toolkit (MRTK). Detta ger en introduktion till tekniska aspekter av skrivning och generering av dokumentation, för att lyfta fram vanliga fallgropar och för att beskriva den rekommenderade skrivstilen.

Själva sidan ska fungera som ett exempel. Därför används det avsedda formatet och de vanligaste markeringsfunktionerna i dokumentationen.


Funktioner och pålägg

I det här avsnittet beskrivs funktioner som behövs ofta. Om du vill se hur de fungerar kan du titta på sidans källkod.

  1. Numrerade listor
    1. Kapslade numrerade listor med minst tre inledande blanksteg
    2. Det faktiska talet i koden är irrelevant. parsning tar hand om inställningen av rätt artikelnummer.
  • Punktlistor
    • Kapslade punktlistor
  • Text i fetstil med * * dubbel asterisk**
  • kursiv text med _ understreck eller en _ * asterisk*
  • Text highlighted as code i en mening med hjälp av ` citat`
  • Länkar till dokumentsidor – riktlinjer för MRTK-dokumentation
  • Länkar till fästpunkter på en sida; fästpunkter skapas genom att blanksteg ersätts med bindestreck och konverteras till gemener

För kodexempel använder vi blocken med tre backticks och ` ` ` anger csharp som språk för syntaxmarkering:

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

När du nämner kod i en mening use a single backtick .

Todos

Undvik att använda TODO:er i dokument, eftersom dessa TODO:er (t.ex. kod-TODO:er) tenderar att ackumuleras och information om hur de ska uppdateras och varför de går förlorade.

Om det är absolut nödvändigt att lägga till en TODO följer du dessa steg:

  1. Skapa ett nytt ärende på Github som beskriver kontexten bakom TODO och ange tillräckligt med bakgrund för att en annan deltagare ska kunna förstå och sedan åtgärda TODO.
  2. Referera till problemets URL i att göra i dokument.

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

Markerade avsnitt

Om du vill markera specifika punkter för läsaren använder > [!NOTE] du , och för att skapa följande > [!WARNING] > [!IMPORTANT] format. Vi rekommenderar att du endast använder anteckningar för allmänna punkter och varnings-/viktiga punkter i särskilda relevanta fall.

Anteckning

Exempel på en anteckning

Varning

Exempel på en varning

Viktigt

Exempel på en viktig kommentar

Sidlayout

Introduktion

Delen direkt efter huvudrubriken i kapitlet bör fungera som en kort introduktion till vad kapitlet handlar om. Gör inte det här för långt, lägg i stället till underrubriker. Dessa gör det möjligt att länka till avsnitt och kan sparas som bokmärken.

Brödtext

Använd toppar på två och tre nivåer för att strukturera resten.

Miniavsnitt

Använd en fet textrad för block som ska stå ut. Vi kan ersätta detta med toppar på fyra nivåer vid något tillfälle.

Avsnittet "Se även"

De flesta sidor bör sluta med ett kapitel som heter Se även. Det här kapitlet är helt enkelt en punktlista med länkar till sidor som är relaterade till det här ämnet. Dessa länkar kan också visas i sidtexten där det är lämpligt, men detta krävs inte. På samma sätt kan sidtexten innehålla länkar till sidor som inte är relaterade till huvudavsnittet. Dessa bör inte tas med i listan Se även. Se kapitlet "Se även" på den här sidan som ett exempel på val av länkar.

Innehållsförteckning

Toc-filer används för att generera navigeringsfälten i MRTK github.io dokumentationen. När en ny dokumentationsfil läggs till kontrollerar du att det finns en post för filen i en av toc.yml-filerna i dokumentationsmappen. Endast artiklar som anges i toc-filerna visas i navigeringen i utvecklardokumenten. Det kan finnas en toc-fil för varje undermapp i dokumentationsmappen som kan länkas till en befintlig toc-fil för att lägga till den som ett underavsnitt i motsvarande del av navigeringen.

Format

Skriva stil

Allmän tumregel: Försök att låta professionell. Det innebär vanligtvis att undvika en "konversationston". Försök också att undvika hyperbol och upplevelser.

  1. Försök inte att vara (alltför) slyna.
  2. Skriv aldrig "I"
  3. Undvik "vi". Detta kan vanligtvis enkelt omformuleras med hjälp av MRTK i stället. Exempel: "vi stöder den här funktionen" -> "MRTK stöder den här funktionen" eller "följande funktioner stöds ...".
  4. På samma sätt kan du försöka undvika "du". Exempel: "Med den här enkla ändringen blir din skuggare konfigurerbar!" -> "Shaders can be made configurable with little effort."
  5. Använd inte "slarviga fraser".
  6. Undvik att låta alltför spänd, vi behöver inte sälja något.
  7. På samma sätt bör du undvika att vara alltför dramatisk. Utropstecken behövs sällan.

Aktivering

  • Använd meningsfall för rubriker. Exempel: versalisera den första bokstaven och namnen, men inget annat.
  • Använd vanlig engelska för allt annat. Det innebär att du inte använder versaler för godtyckliga ord , även om de har en särskild betydelse i den kontexten. Föredrar kursiv text för att markera vissa ord, se nedan.
  • När en länk bäddas in i en mening (vilket är den föredragna metoden) använder standardkapitlet alltid versaler, vilket bryter regeln om godtycklig versal i texten. Använd därför ett anpassat länknamn för att åtgärda versaler. Här är till exempel en länk till dokumentationen för gränskontroll.
  • Använd versaler för namn, till exempel Unity.
  • Använd INTE versaler för "editor" när du skriver Unity-redigeraren.

Betoning och markering

Det finns två sätt att betona eller markera ord, göra dem fetstilt eller göra dem kursivt. Effekten av fet text är att fet text visas och därför lätt kan märkas när du rullar en text eller bara rullar över en sida. Fetstil är bra för att markera fraser som människor bör komma ihåg. Använd dock fet text sällan, eftersom den vanligtvis är störande.

Ofta vill man antingen "gruppera" något som tillhör logiskt tillsammans eller lyfta fram en viss term, eftersom den har en särskild betydelse. Sådana saker behöver inte stå ut ur den övergripande texten. Använd kursiv text som en enkel metod för att markera något.

När ett filnamn, en sökväg eller en menypost nämns i text föredrar du på samma sätt att göra det kursivt för att gruppera det logiskt, utan att vara störande.

I allmänhet bör du försöka undvika onödiga textmarkeringar. Särskilda termer kan markeras en gång för att göra läsaren medveten, upprepa inte sådan markering i hela texten, när den inte längre har något syfte och bara blir störande.

Omnämnande av menyposter

När du nämner en menypost som en användare ska klicka på är den aktuella konventionen: Project > Files > Create > Leaf

Infoga så många användbara länkar till andra sidor som möjligt, men varje länk bara en gång. Anta att en läsare klickar på varje länk på sidan och tänker på hur besvärligt det skulle vara om samma sida öppnas 20 gånger.

Prioritera länkar inbäddade i en mening:

Undvik externa länkar, de kan bli inaktuella eller innehålla upphovsrättsskyddat innehåll.

När du lägger till en länk bör du överväga om den även ska visas i avsnittet Se även. Kontrollera på samma sätt om en länk till den nya sidan ska läggas till på sidan länkad till.

Bilder/skärmbilder

Använd skärmbilder sparsamt. Det är mycket arbete att underhålla bilder i dokumentationen, små ändringar i användargränssnittet kan göra många skärmbilder inaktuella. Följande regler minskar underhållsarbetet:

  1. Använd inte skärmbilder för saker som kan beskrivas i text. I synnerhet bör du aldrig skärmbilda ett egenskapsrutnät för det enda syftet att visa egenskapsnamn och värden.
  2. Ta inte med saker i en skärmbild som är irrelevanta för det som visas. När en renderingseffekt visas kan du till exempel skapa en skärmbild av visningsområdet, men exkludera alla användargränssnitt runt det. Visa ett användargränssnitt och försök att flytta runt fönster så att endast den viktiga delen finns i avbildningen.
  3. När du inkluderar skärmbildsgränssnittet visar du bara de viktiga delarna. När du till exempel pratar om knappar i ett verktygsfält kan du skapa en liten bild som visar de viktiga knapparna i verktygsfältet, men exkludera allt runt den.
  4. Använd endast bilder som är enkla att återskapa. Det innebär att du inte ska färgmarkörer eller markeringar i skärmbilder. För det första finns det ändå inga konsekventa regler för hur dessa ska se ut. För det andra är det ytterligare arbete att återskapa en sådan skärmbild. Beskriv i stället de viktiga delarna i texten. Det finns undantag till den här regeln, men de är ovanliga.
  5. Naturligtvis är det mycket mer arbete att återskapa en animerad GIF. Förvänta dig att vara ansvarig för att återskapa den till slutet av tiden, eller förvänta dig att personer kastar ut den, om de inte vill ägna den tiden.
  6. Håll nere antalet bilder i en artikel. Ofta är en bra metod att göra en övergripande skärmbild av ett verktyg som visar allt och sedan beskriva resten i text. Det gör det enkelt att ersätta skärmbilden vid behov.

Några andra aspekter:

  • Redigeringsgränssnittet för skärmbilder bör använda ljusgrå temaredigerare eftersom alla användare inte har åtkomst till det mörka temat och vi vill att allt ska vara så konsekvent som möjligt.
  • Standardbildens bredd är 500 bildpunkter, eftersom den visas bra på de flesta bildskärmar. Försök att inte avvika för mycket från den. Bredden på 800 bildpunkter ska vara den högsta.
  • Använd PNG:er för skärmbilder av användargränssnittet.
  • Använd PNG:er eller JPEG för skärmbilder av 3D-visningsområdet. Prioritera kvalitet framför komprimeringsförhållande.

Lista över komponentegenskaper

När du dokumenterar en lista med egenskaper använder du fet text för att markera egenskapsnamnet och sedan radbrytningar och vanlig text för att beskriva dem. Använd inte underkapitlen eller punktlistor.

Glöm inte heller att avsluta alla meningar med en punkt.

Checklista för sidslut

  1. Se till att riktlinjerna för det här dokumentet följs.
  2. Bläddra igenom dokumentstrukturen och se om det nya dokumentet kan nämnas under avsnittet Se även på andra sidor.
  3. Om det är tillgängligt ska du be någon med kunskap om ämnet att korrekt läsa sidan för teknisk korrekthet.
  4. Be någon att korrekt läsa sidan för stil och formatering. Det kan vara någon som inte är bekant med ämnet, vilket också är en bra idé för att få feedback om hur begriplig dokumentationen är.

Källdokumentation

API-dokumentationen genereras automatiskt från MRTK-källfilerna. För att underlätta detta måste källfilerna innehålla följande:

Förutom ovanstående bör koden vara väl kommenterad för att möjliggöra underhåll, felkorrigeringar och enkel anpassning.

Sammanfattningsblock för klass, struct och uppräkning

Om en klass, struct eller enum läggs till i MRTK måste dess syfte beskrivas. Detta ska ske i form av ett sammanfattningsblock ovanför klassen .

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

Om det finns beroenden på klassnivå bör de dokumenteras i ett kommentarsblock direkt under sammanfattningen.

/// <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-begäranden som skickas utan sammanfattningar för klasser, strukturer eller uppräkningar godkänns inte.

Egenskap, metod, händelsesammanfattningsblock

Egenskaper, metoder och händelser (PME:er) samt fält ska dokumenteras med sammanfattningsblock, oavsett kodsynlighet (offentligt, privat, skyddat och internt). Verktyget för dokumentationsgenerering ansvarar för att filtrera bort och publicera endast offentliga och skyddade funktioner.

Obs! Ett sammanfattningsblock krävs inte för Unity-metoder (t.ex. Aktiv, Start, Uppdatera).

PME-dokumentation krävs för att en pull-begäran ska godkännas.

Som en del av ett PME-sammanfattningsblock krävs betydelsen och syftet med parametrar och returnerade data.

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

Funktionsintroduktionsversion och beroenden

Som en del av API-sammanfattningsdokumentationen bör information om den MRTK-version där funktionen introducerades och eventuella beroenden dokumenteras i ett kommentarsblock.

Beroenden bör innehålla tilläggs- och/eller plattformsberoenden.

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

Serialiserade fält

Det är en bra idé att använda Unitys knappbeskrivningsattribut för att tillhandahålla körningsdokumentation för ett skripts fält i kontrollverktyget.

Så att konfigurationsalternativen ingår i API-dokumentationen måste skript inkludera minst knappbeskrivningsinnehållet i ett sammanfattningsblock.

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

Uppräkningsvärden

När du definierar och uppräkning måste koden även dokumentera innebörden av uppräkningsvärdena med hjälp av ett sammanfattningsblock. Kommentarsblock kan också användas för att ge ytterligare information för att förbättra förståelsen.

/// <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 om hur du gör

Många användare av Mixed Reality Toolkit kanske inte behöver använda API-dokumentationen. Dessa användare kommer att dra nytta av våra färdiga, återanvändbara prefabs och skript för att skapa sina upplevelser.

Varje funktionsområde innehåller en eller flera Markdown-filer (.md) som på en ganska hög nivå beskriver vad som tillhandahålls. Beroende på storleken och/eller komplexiteten för ett visst funktionsområde kan det finnas behov av ytterligare filer, upp till en per funktion.

När en funktion läggs till (eller användningen ändras) måste översiktsdokumentation tillhandahållas.

Som en del av den här dokumentationen bör i-avsnitt, inklusive bilder, tillhandahållas för att hjälpa kunder som är nya med en funktion eller ett koncept när de kommer igång.

Designdokumentation

Mixed Reality ger en möjlighet att skapa helt nya världar. En del av detta handlar troligen om att skapa anpassade tillgångar för användning med MRTK. För att göra det så friktionsfritt som möjligt för kunderna bör komponenterna tillhandahålla designdokumentation som beskriver all formatering eller andra krav för konsttillgångar.

Några exempel där designdokumentation kan vara till hjälp:

  • Markörmodeller
  • Visualiseringar för rumslig mappning
  • Ljudeffektsfiler

Den här typen av dokumentation rekommenderas starkt och kan begäras som en del av en granskning av pull-begäran.

Detta kan eller kanske inte skiljer sig från designrekommendationen på WEBBPLATSEN FÖR MS-utvecklare

Prestandaanteckningar

Vissa viktiga funktioner har en prestandakostnad. Den här koden beror ofta på hur de är konfigurerade.

Exempel:

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.

Prestandaanteckningar rekommenderas för processor- och/eller GPU-tunga komponenter och kan begäras som en del av en granskning av pull-begäran. Eventuella prestandaanteckningar ska inkluderas i API:et och översiktsdokumentationen.

Icke-bakåtkompatibla ändringar

Dokumentationen om större ändringar består av en toppnivåfil som länkar till varje funktionsområdes enskilda breaking-changes.md.

Funktionsområdet för breaking-changes.md ska innehålla listan över alla kända större ändringar för en viss version samt historiken för att bryta ändringar från tidigare versioner.

Exempel:

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

Informationen på funktionsnivå och breaking-changes.md sammanställs till viktig information för varje ny MRTK-version.

Alla större ändringar som ingår i en ändring måste dokumenteras som en del av en pull-begäran.

Verktyg för att redigera MarkDown

Visual Studio Code är ett bra verktyg för att redigera Markdown-filer som ingår i MRTK:s dokumentation.

När du skriver dokumentation rekommenderar vi också starkt att du installerar följande två tillägg:

  • Docs Markdown-tillägg för Visual Studio Code – Använd Alt + M för att öppna en meny med redigeringsalternativ för dokument.

  • Stavningskontroll i kod – felstavade ord kommer att understrukits. högerklicka på ett felstavat ord för att ändra det eller spara det i ordlistan.

Båda dessa levereras i Microsofts publicerade Docs-redigeringspaket.

Se även