Dokumentációs irányelvek


Funkciók és jelölő

Ez a szakasz a gyakran szükséges funkciókat ismerteti. A lap forráskódja azt is bemutatja, hogyan működnek.

  1. Számolt listák
    1. Legalább 3 kezdő szóközt tartalmazó, számba ágyazott listák
    2. A kód tényleges száma irreleváns; Az parsing gondoskodik a megfelelő elemszám beállításéről.
  • Listajeles listák
    • Listajeles listák beágyazott felsorolása
  • Félkövérrel szedett szöveg **dupla csillaggal**
  • dőltszöveg _underscore_ vagy *egy csillaggal*
  • Egy highlighted as code mondaton belüli szöveg "backquotes használatával"
  • Hivatkozások a dokumentumoldalak MRTK-dokumentációs útmutatóira
  • Hivatkozás egy oldalon belüli horgonyra; A horgonyok úgy vannak kialakítva, hogy a szóközöket kötőjelekre cserélik, és kisbetűssé alakítják

Kódmintákhoz a blokkokat három "" visszatolással használjuk, és a szintaxiskiemelő nyelvként a csharp nyelvet adhatja meg:

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

Ha egy mondatban említ use a single backtick kódot.

Todos

Kerülje a toDO-k docsban való használatát, mivel idővel ezek a TODO-k (például a kód-TODO-k) általában összegyűlnek, és információt tartalmaznak a frissítésükről és az elesésükről.

Ha feltétlenül szükség van egy TODO hozzáadására, kövesse az alábbi lépéseket:

  1. Jelentsen be egy új problémát a GitHubon, írja le a toDO hátterét, és adjon meg elegendő hátteret ahhoz, hogy egy másik közreműködő megértse és fel tudja használni a toDO-t.
  2. Hivatkozhat a probléma URL-címére a dokumentumokban találhatódoikban.

<!-- TODO: A probléma https://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE rövid összefoglalója –>

Kiemelt szakaszok

Az olvasó adott pontjainak kiemelésére használja a [! MEGJEGYZÉS] , [! FIGYELMEZTETÉS] , és [! FONTOS] a következő stílusok előállításához. Az általános pontokhoz és a figyelmeztetési/fontos pontokhoz csak különleges releváns esetekhez ajánlott megjegyzéseket használni.

Megjegyzés

Példa megjegyzésre

Figyelmeztetés

Példa figyelmeztetésre

Fontos

Példa fontos megjegyzésre

Oldalelrendezés

Bevezetés

A fejezetcím utáni résznek rövid bevezetésként kell szolgálnia a fejezet lényegét. Ne tegye ezt túl hosszúra, inkább adjon hozzá alcímeket. Ezek lehetővé teszik a szakaszokra mutató hivatkozásokat, és könyvjelzőként menthetők.

Fő törzs

A többi struktúra felépítéséhez használjon két- és háromszintű címsorokat.

Mini szakaszok

Használjon félkövér szövegsort a jól kivetnit blokkok számára. Ezt egy bizonyos ponton négyszintű főcímekkel helyettesítheti.

"Lásd még" szakasz

A legtöbb oldalnak egy See also (Lásd még) nevű fejezettel kell végződni. Ez a fejezet egyszerűen a témakörrel kapcsolatos oldalakra mutató hivatkozások felsorolása. Ezek a hivatkozások szükség esetén az oldal szövegében is megjelenhetnek, de ez nem kötelező. Hasonlóképpen, az oldal szövege tartalmazhat olyan oldalakra mutató hivatkozásokat, amelyek nem kapcsolódnak a fő témakörhez, de nem szabad őket szerepeltetni a Lásd még listában. Tekintse meg az oldal "Lásd még" fejezetét a hivatkozások választásának példájaként.

Tartalomjegyzék (TARTALOMJEGYZÉK)

A toc fájlok az MRTK-dokumentáció navigációs sávjainak létrehozásához github.io használhatók. Új dokumentációs fájl hozzáadásakor győződjön meg arról, hogy a fájlnak van bejegyzése a dokumentációs mappa egyik toc.yml fájljában. A fejlesztői dokumentumok navigációs sávján csak a toc filesban felsorolt cikkek fognak megjelenik. A dokumentációs mappa minden almappában lehet egy-egy toc fájl, amely bármely meglévő toc fájlhoz csatolható, hogy a navigáció megfelelő részében alszakaszként hozzáadja azt.

Stílus

Írásstílus

Általános általános szabály: Próbáljon professzionálisnak hangzani. Ez általában a "beszélgetési hangvétel" elkerülését jelenti. Kerülje a hiperbola és az érzetek elkerülését is.

  1. Ne próbáljon túl sok (túl sok) etikát látni.
  2. Soha ne írja meg az "I"
  3. Kerülje a "we" (mi) et. Ezt általában egyszerűen át lehet fogalmazni, ehelyett az "MRTK" használatával. Például: "támogatjuk ezt a funkciót" – "Az MRTK támogatja ezt a funkciót" vagy > "a következő funkciók támogatottak ...".
  4. Hasonlóképpen próbálja meg elkerülni a "You" (Ön) et. Példa: "Ezzel az egyszerű módosítással az árnyékoló konfigurálhatóvá válik!" – "A árnyékolók kevés erőfeszítéssel > konfigurálhatók."
  5. Ne használjon "hanyag kifejezéseket".
  6. Kerülje a túl izgatottnak hangzást, semmit sem kell értékesítenünk.
  7. Hasonlóképpen kerülje a túl drámaiságot. A felkiáltójelre ritkán van szükség.

Nagybetűs

  • Használja a Sentence case (Mondateset) a főcímek esetében. Ie. Az első betűt és a neveket nagybetűsre kell írni, de semmi másra.
  • Minden máshoz használjon normál angolt. Ez azt jelenti, hogy nenagybetűssé tegye a tetszőleges szavakat, még akkor sem, ha az adott kontextusban speciális jelentéssel bírnak. A dőlt szöveg kiemelését részesíti előnyben, lásd alább.
  • Amikor egy hivatkozás egy mondatba van beágyazva (amely az előnyben részesített módszer), a szabványos fejezet neve mindig nagybetűket használ, így a szövegben nem található tetszőleges kis- és nagybetű. Ezért használjon egyéni hivatkozásnevet a kis- és nagybetűk kijavítása érdekében. Példaként itt található egy hivatkozás, amely a határvezérlő dokumentációra mutat.
  • Nagybetűs neveket, például Unityt.
  • Unity-szerkesztő írásakor NE nagybetűvel írja a szerkesztőt.

Kiemelés és kiemelés

A szavakat kétféleképpen emelheti ki vagy emelheti ki: félkövérre vagy dőltre emelheti ki őket. A félkövér szövegnek az a hatása, hogy a félkövér szöveg ki van vava, így könnyen észrevehető, amikor egy szöveget lesiklunk, vagy akár csak végiggörgetünk egy oldalt. A félkövér jól kiemeli azokat a kifejezéseket, amelyekre az embereknek emlékezniük kell. A félkövér szöveget azonban ritkánhasználja, mert az általában zavaró.

Gyakran előfordul, hogy egy logikailag egymáshoz tartozó dolgot "csoportba" szeretne csoportosni, vagy kiemelni egy adott kifejezést, mert az különleges jelentéssel bír. Az ilyen dolgoknak nem kell a teljes szövegből kiosonni. A dőlt szöveg egyszerű metódusként való használatával kiemelheti a szövegeket.

Hasonlóképpen, ha egy fájlnév, elérési út vagy menübejegyzés szerepel a szövegben, inkább dőlt betűsre tegye, hogy logikusan csoportosuljon, és ne terelje el a figyelmet.

Általában kerülje a szükségtelen szövegkiemelőt. A speciális kifejezések egyszer emelhetőek ki, hogy az olvasó észrevehető legyen, ne ismételje meg az ilyen kiemeléseket a teljes szövegben, ha már nincs célja, és csak elvonja a figyelmet.

Menübejegyzések megemlítés

Amikor megemlít egy menübejegyzést, amelyre a felhasználónak kattintanának, a jelenlegi konvenció a következő: Project Fájlok levél >> létrehozása

A lehető legtöbb hasznos hivatkozást szúrjon be más oldalakra, de mindegyiket csak egyszer. Tegyük fel, hogy egy olvasó az oldal összes hivatkozására kattint, és gondolja át, milyen milyen lenne, ha ugyanaz az oldal 20-szor megnyílik.

Mondatba ágyazott hivatkozások előnyben részesítve:

Kerülje a külső hivatkozásokat, mert ezek elavulttá válhatnak, vagy szerzői jogokkal védett tartalmakat tartalmazhatnak.

Hivatkozás hozzáadásakor vegye figyelembe, hogy azt is fel kell-e sorolni a Lásd még szakaszban. Hasonlóképpen ellenőrizze, hogy hozzá kell-e adni az új lapra mutató hivatkozást a hivatkozott oldalhoz.

Képek/képernyőképek

Csak ritkán használjon képernyőképeket. A lemezképek dokumentációban való karbantartása sok munkát jelent, a felhasználói felület kisebb módosításai pedig sok képernyőképet elavulttá tenek. A következő szabályok csökkentik a karbantartási munkát:

  1. Ne használjon képernyőképeket a szövegben leírt dolgokhoz. Különösen ne képernyőfelvételt készíteni egy tulajdonságrácsról kizárólag a tulajdonságnevek és -értékek megjelenítése céljából.
  2. A képernyőképen ne szerepeljenek olyan dolgok, amelyek irrelevánsak a bemutatottak szempontjából. Ha például megjelenik egy renderelési hatás, készítsen egy képernyőképet a nézetről, de zárja ki a rajta látható felhasználói felületet. A felhasználói felület megjelenítésével próbálja meg úgy áthelyezni az ablakokat, hogy csak ez a fontos rész látható a képen.
  3. A képernyőfelvételek felhasználói felületének megjelenítésekor csak a fontos részek mutassanak. Ha például egy eszköztár gombjairól van szó, készítsen egy kis képet, amely a fontos eszköztárgombokat jeleníti meg, de zár ki mindent, ami körülveszi.
  4. Csak könnyen reprodukálható képeket használjon. Ez azt jelenti, hogy ne rajzolja a jelölőket és a kiemeléseket képernyőképekbe. Először is nincsenek konzisztens szabályok, hogy ezek hogyan néznek ki. Másodszor, az ilyen képernyőképek reprodukálása további erőfeszítést igényel. Ehelyett írja le a szöveg fontos részeit. Vannak kivételek a szabály alól, de ritkán fordulnak elő.
  5. Nyilvánvaló, hogy sokkal több erőfeszítést igényel egy animált GIF létrehozása. Számíthat rá, hogy az idő végéig újra létre kell hoznia, vagy elvárni, hogy a rendszer kiadja, ha nem szeretné ezt az időt tölteni.
  6. Tartsa alacsonyan a cikkben látható képek számát. Gyakran jó módszer, ha egy általános képernyőképet készít egy eszközről, amely mindent bemutat, majd leírja a többit szövegként. Ez megkönnyíti a képernyőkép szükség esetén való cseréjét.

Néhány egyéb szempont:

  • A képernyőképek szerkesztőfelületének világosszürke témaszerkesztőt kell használnia, mivel nem minden felhasználó fér hozzá a sötét témához, és szeretnénk a lehető leg konzisztensebb dolgokat használni.
  • Az alapértelmezett képszélesség 500 képpont, mivel ez a legtöbb monitoron jól jelenik meg. Próbáljon meg nem túl sokat eltenni tőle. A maximális szélesség 800 képpont.
  • Használjon PNG-ket a felhasználói felület képernyőképéhez.
  • PNG-ket vagy JPG-ket használhat a 3D-s nézetportok képernyőképeihez. A minőség előnyben részesítve a tömörítési arányhoz viszonyított értékhez viszonyítottan.

Összetevő tulajdonságainak listája

A tulajdonságok listájának dokumentálásakor félkövér szöveggel jelölje ki a tulajdonság nevét, majd sortöréseket és normál szöveget a leírásukhoz. Ne használjon al fejezeteket vagy listajeles listát.

Emellett ne felejtsen el minden mondatot ponttal befejezni.

Oldal befejezési ellenőrzőlistája

  1. Győződjön meg arról, hogy követte a dokumentum irányelveit.
  2. Böngésszen a dokumentumszerkezetben, és nézze meg, hogy megemlítheti-e az új dokumentumot más oldalak See also (Lásd még) szakaszában.
  3. Ha elérhető, a technikai helyesség érdekében legyen egy olyanja, aki ismeri a témakör proof-read oldalát.
  4. A stílust és a formázást valakinek meg kell olvasnia az oldalon. Ez lehet olyan, aki nem ismeri a témakört, és szintén jó ötlet visszajelzést kapni arról, hogy mennyire érthető a dokumentáció.

Forrásdokumentáció

Az API-dokumentáció automatikusan létrejön az MRTK-forrásfájlokból. Ennek megkönnyítése érdekében a forrásfájloknak a következőket kell tartalmazni:

A fentiek mellett a kódot érdemes jól megjegyzésbe tenni, hogy lehetővé tegye a karbantartást, a hibajavításokat és a könnyű testreszabást.

Osztály, strukturál, felsorolás összegzési blokkok

Ha osztályt, strukturállyal vagy felsorolást adnak hozzá az MRTK-hoz, le kell írni annak célját. Ez az osztály fölötti összesítő blokk formájában fog lehatolódni.

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

Ha vannak osztályszintű függőségek, ezeket egy megjegyzésblokkban kell dokumentálni, közvetlenül az összegzés alatt.

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

Az osztályok, struktúrák vagy enumok összegzése nélkül elküldött lekéréses kérelmeket a rendszer nem hagyja jóvá.

Tulajdonság, metódus, eseményösszegzési blokkok

A tulajdonságokat, metódusokat és eseményeket (PME-k), valamint a mezőket összegző blokkokkal kell dokumentálni, függetlenül a kód láthatóságától (nyilvános, privát, védett és belső). A dokumentáció-generáló eszköz feladata, hogy kiszűrje és közzéteje csak a nyilvános és védett funkciókat.

MEGJEGYZÉS: A Unity-metódusok (például: Az idő, az indítás, az update) esetén nincs szükség összegzési blokkra.

A PME dokumentációja szükséges a lekéréses kérelmek jóváhagyásához.

A PME összefoglaló blokkjának részeként szükség van a paraméterek és a visszaadott adatok jelentésére és rendeltetésére.

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

Funkcióbevezetési verzió és függőségek

Az API összefoglaló dokumentációjának részeként a funkció bevezetési MRTK-verziójával és az esetleges függőségekkel kapcsolatos információkat egy megjegyzésblokkban kell dokumentálni.

A függőségek lehetnek bővítmény- és/vagy platformfüggőségek.

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

Szerializált mezők

A Unity elemleírás-attribútumával hasznos lehet a szkript mezőinek futásidejű dokumentációját biztosítani az Inspectorban.

Ahhoz, hogy a konfigurációs beállítások szerepeljenek az API-dokumentációban, a szkriptnek legalább az elemleírás tartalmát tartalmaznia kell egy összefoglaló blokkban.

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

Enumerálás értékei

A definiálás és enumerálás során a kódnak az enumerálás értékeinek jelentését is dokumentálni kell egy összefoglaló blokk használatával. Megjegyzésblokkokkal további részleteket is meg lehet adni a jobb megértés érdekében.

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

How-to documentation (Dokumentáció)

Előfordulhat, hogy a Mixed Reality toolkit számos felhasználójának nem kell használnia az API-dokumentációt. Ezek a felhasználók kihasználják az előre létrehozott, újrahasználható előfóbok és szkriptek előnyeit a felhasználói élmények létrehozásához.

Minden egyes funkcióterület egy vagy több markdown- (.md) fájlt tartalmaz, amelyek viszonylag magas szinten írják le a megadott adatokat. Egy adott szolgáltatásterület méretétől és/vagy összetettségétől függően további fájlokra lehet szükség, szolgáltatásonként legfeljebb egy fájlra.

Egy funkció hozzáadásakor (vagy a használat megváltozik) meg kell adni az áttekintő dokumentációt.

A dokumentáció részeként az első lépésekhez segítséget kell nyújtani az ügyfeleknek, hogy segítséget tudjanak nyújtani az új funkciókhoz vagy fogalmakhoz.

Tervezési dokumentáció

Mixed Reality lehetőséget nyújt teljesen új világok létrehozására. Ennek egy része valószínűleg magában foglalja az MRTK-val használható egyéni eszközök létrehozását. Annak érdekében, hogy ez a lehető legnagyobb súrlódást tegye lehetővé az ügyfelek számára, az összetevőknek olyan tervezési dokumentációt kell nyújtaniuk, amely leírja a képi eszközök formázását vagy egyéb követelményeit.

Néhány példa, ahol a tervezési dokumentáció hasznos lehet:

  • Kurzormodellek
  • Térbeli leképezési vizualizációk
  • Hanghatásfájlok

Ez a dokumentációtípus erősen ajánlott, és a lekéréses kérelmek felülvizsgálatának részeként kérheti.

Ez lehet, hogy nem különbözik az MS Developer webhelyen található tervezési javaslattól

Teljesítményre vonatkozó megjegyzések

Néhány fontos funkció teljesítményköltséggel jár. Ez a kód gyakran nagyon is függ a konfigurációjuktól.

Például:

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.

A teljesítményre vonatkozó megjegyzések processzor- és/vagy GPU-alapú nagy kapacitású összetevőkhöz ajánlottak, és lekéréses kérelmek felülvizsgálatának részeként kérhetőek lekéréses kérelmekhez. A vonatkozó teljesítményjegyeket szerepelnie kell az API és az áttekintő dokumentációban.

Kompatibilitástörő változások

A nem megfelelő változások dokumentációja egy legfelső szintű fájlból áll, amely az egyes funkciók területének egyéni breaking-changes.md.

A szolgáltatás breaking-changes.md a fájloknak tartalmazni kell az adott kiadás összes ismert, feltörést el nem hozó változásának listáját, valamint a korábbi kiadásokhoz való frisseső változások előzményeit.

Például:

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

A szolgáltatásszinten belül található breaking-changes.md összesítve lesznek az új MRTK-kiadások kibocsátási megjegyzéseibe.

A változások részét képezi minden feltörést eltolt változást lekéréses kérelem részeként kell dokumentálni.

MarkDown-szerkesztési eszközök

Visual Studio Code remek eszköz az MRTK dokumentációjában található Markdown-fájlok szerkesztéséhez.

A dokumentáció írásakor a következő két bővítmény telepítése is erősen ajánlott:

  • Docs Markdown-bővítmény a Visual Studio Code-hoz – Az Alt+M billentyűkombinációval megjelenik a dokumentumok szerzői lehetőségeinek menüje.

  • Kód helyesírás-ellenőrzője – a hibásan írt szavak alá lesznek húzva; kattintson a jobb gombbal egy hibásan írt szóra a módosításhoz vagy a szótárba mentéshez.

Mindkettő a Microsoft által közzétett Docs Authoring Pack csomagba van csomagolva.

Lásd még

MRTK

Ez a dokumentum az Mixed Reality Toolkit (MRTK) dokumentációs irányelveit és szabványait ismerteti. Ez bevezetést nyújt a dokumentáció írásának és generációjának technikai aspektusaiba, hogy kiemelje a gyakori buktatókat, és leírja az ajánlott írási stílust.

Magának az oldalnak kell példaként szolgálnia, ezért a kívánt stílust és a dokumentáció leggyakoribb jelölő funkcióit használja.