Sdílet prostřednictvím

Pokyny pro dokumentaci – MRTK2

  • Článek
MRTK

Tento dokument popisuje pokyny a standardy dokumentace pro sadu nástrojů Mixed Reality (MRTK). Tento článek obsahuje úvod k technickým aspektům dokumentace pro psaní a generování, ke zvýraznění běžných nástrah a k popisu doporučeného stylu psaní.

Samotná stránka by měla sloužit jako příklad, a proto používá zamýšlený styl a nejběžnější značkové funkce dokumentace.

Funkce a revize

Tato část popisuje často potřebné funkce. Pokud chcete zjistit, jak fungují, podívejte se na zdrojový kód stránky.

  1. Číslovaný seznam
    1. Vnořené číslovaný seznamy s alespoň 3 počátečními prázdnými mezerami
    2. Skutečné číslo v kódu je irelevantní; Analýza se postará o nastavení správného čísla položky.
  • Seznamy s odrážkami
    • Vnořené seznamy s odrážkami
  • Text tučně s **dvojitou hvězdičkou**
  • kurzíva s podtržítkem nebo *jedinou hvězdičkou*
  • Text highlighted as code ve větě using backquotes
  • Odkazy na stránky dokumentace MRTK – pokyny k dokumentaci
  • Odkazy na kotvy v rámci stránky; kotvy jsou tvořeny nahrazením mezer pomlčkami a převodem na malá písmena

Pro ukázky kódu používáme bloky se třemi backticks '' a jako jazyk pro zvýraznění syntaxe specifikujeme csharp :

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

Při zmínce kódu ve větě use a single backtick.

ToDOs

Nepoužívejte objekty TODO v dokumentech, protože v průběhu času se tyto objekty TODO (jako kód TODO) obvykle shromažďují a informace o tom, jak by se měly aktualizovat a proč se ztratí.

Pokud je nezbytně nutné přidat todo, postupujte takto:

  1. Vytvořte nový problém na GitHubu s popisem kontextu, který je za todo, a poskytněte dostatek pozadí, aby ho mohl pochopit a pak vyřešit jiný přispěvatel.
  2. Odkaz na adresu URL problému v seznamu úkolů v dokumentaci

<-- todohttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Stručný rozostření problému ->

Zvýrazněné oddíly

Pokud chcete zvýraznit konkrétní body čtenáře, použijte > [! POZNÁMKA] , > [! VAROVÁNÍ] a > [! DŮLEŽITÉ] k vytvoření následujících stylů. Doporučuje se používat poznámky pro obecné body a upozornění /důležité body pouze pro zvláštní relevantní případy.

Poznámka:

Příklad poznámky

Upozorňující

Příklad upozornění

Důležité

Příklad důležitého komentáře

Rozložení stránky

Úvod

Část hned po názvu hlavní kapitoly by měla sloužit jako krátký úvod k tématu. Nevytvádej to moc dlouho, místo toho přidejte dílčí nadpisy. Ty umožňují odkazovat na oddíly a dají se uložit jako záložky.

Hlavní tělo

Pomocí dvouúrovňových a tříúrovňových nadpisů můžete zbytek strukturovat.

Mini oddíly

Pro bloky, které by měly vyniknout, použijte tučný řádek textu. V určitém okamžiku bychom to mohli nahradit čtyřúrovňovými nadpisy.

Část Viz také

Většina stránek by měla končit také kapitolou s názvem Viz. Tato kapitola je jednoduše odrážkovým seznamem odkazů na stránky související s tímto tématem. Tyto odkazy se také můžou zobrazit v textu stránky, kde je to vhodné, ale není to nutné. Podobně text stránky může obsahovat odkazy na stránky, které nesouvisí s hlavním tématem, neměly by být zahrnuty také do seznamu Viz. Podívejte se na kapitolu "Viz také" této stránky jako příklad pro výběr odkazů.

Obsah (OBSAH)

Soubory s obsahem se používají ke generování navigačních panelů v dokumentaci github.io MRTK. Při každém přidání nového souboru dokumentace se ujistěte, že soubor obsahuje položku v jednom ze toc.yml souborů složky dokumentace. V navigaci v dokumentaci pro vývojáře se zobrazí jenom články uvedené v souborech obsahu. Pro každou podsložku ve složce dokumentace může existovat soubor s obsahem, který se dá propojit s jakýmkoli existujícím souborem obsahu a přidat ho jako pododdíl odpovídající části navigace.

Styl

Styl psaní

Obecné pravidlo: Zkuste znít profesionálně. To obvykle znamená vyhnout se "konverzačnímu tónu". Také se snažte vyhnout hyperbole a senzačnímu.

  1. Nepokoušejte se být (příliš) legrační.
  2. Nikdy nepište "I"
  3. Vyhněte se "my". To se obvykle dá snadno přehrabovat pomocí mrTK. Příklad: "Tuto funkci podporujeme" –> "MRTK tuto funkci podporuje" nebo "podporují se následující funkce...".
  4. Podobně se snažte vyhnout "vy". Příklad: "S touto jednoduchou změnou se shader stane konfigurovatelným!" –> "Shadery lze konfigurovat s malým úsilím".
  5. Nepoužívejte "sloppy phrases".
  6. Vyhněte se příliš nadšení, nemusíme nic prodávat.
  7. Podobně se vyhněte příliš dramatickým. Vykřičníky jsou zřídka potřeba.

Velká písmena

  • Pro nadpisy používejte velká a velká písmena. Ie. velká písmena a jména, ale nic jiného.
  • Používejte běžnou angličtinu pro všechno ostatní. To znamená , že nepoužívejte velká písmena libovolných slov, i když mají v tomto kontextu zvláštní význam. Preferujte kurzívu pro zvýraznění určitých slov, viz níže.
  • Pokud je odkaz vložen do věty (což je upřednostňovaná metoda), standardní název kapitoly vždy používá velká písmena, čímž se přeruší pravidlo bez libovolného velká písmena uvnitř textu. Proto k opravě velkých písmen použijte vlastní název odkazu. Tady je příklad odkazu na dokumentaci k ovládacím prvkům hranic.
  • Zadejte velká písmena, například Unity.
  • Při psaní editoru Unity nepoužívejte velká písmena "editor".

Zdůraznění a zvýraznění

Existují dva způsoby, jak zvýraznit nebo zvýraznit slova, zvýraznit je tučným písmem nebo kurzívou. Efektem tučného textu je, že se tučný text vylepí , a proto si můžete snadno všimnout, když přeskočíte část textu nebo se dokonce jen posunete na stránku. Tučné písmo je skvělé pro zvýraznění frází, které by si lidé měli pamatovat. Používejte však tučný text zřídka, protože je obvykle rušivý.

Často chce buď "seskupit" něco, co patří logicky dohromady, nebo zvýraznit konkrétní termín, protože má zvláštní význam. Takové věci nemusí vyniknout z celkového textu. Pokud chcete něco zvýraznit, použijte kurzívu jako jednoduchou metodu.

Podobně platí, že pokud je název souboru, cesta nebo položka nabídky zmíněny v textu, raději chcete, aby kurzíva byla logicky seskupována, aniž by vás rušily.

Obecně se snažte vyhnout zbytečnému zvýrazňování textu. Speciální termíny lze jednou zvýraznit, aby čtenář věděl, neopakujte takové zvýraznění v celém textu, pokud už slouží k žádnému účelu a jen ruší.

Zmínka o položkách nabídky

Při zmínce položky nabídky, na kterou má uživatel kliknout, je aktuální konvence: Soubory projektu > > vytvořit > list

Vložte co nejvíce užitečných odkazů na jiné stránky, ale každý odkaz pouze jednou. Předpokládejme, že čtenář klikne na každý odkaz na stránce, a zamyslete se nad tím, jak otravné by to bylo, pokud stejná stránka otevře 20krát.

Preferovat odkazy vložené do věty:

Vyhněte se externím odkazům, můžou být zastaralé nebo obsahují obsah s autorským právem.

Při přidávání odkazu zvažte, jestli by měl být uvedený také v části Viz . Podobně zkontrolujte, jestli se má odkaz na novou stránku přidat na odkaz na stránku.

Obrázky / snímky obrazovky

Používejte snímky obrazovky střídmě. Údržba obrázků v dokumentaci je hodně práce, malé změny uživatelského rozhraní můžou dělat spoustu snímků obrazovky zastaralá. Následující pravidla snižují úsilí o údržbu:

  1. Nepoužívejte snímky obrazovky pro věci, které je možné popsat v textu. Zvlášť platí, že nikdy nezachytávejte mřížku vlastností pro jediný účel zobrazení názvů a hodnot vlastností.
  2. Nezahrnujte do snímku obrazovky věci, které nejsou relevantní pro to, co se zobrazí. Když se například zobrazí efekt vykreslování, vytvořte snímek obrazovky oblasti zobrazení, ale vyloučíte kolem něj jakékoli uživatelské rozhraní. Když se zobrazí nějaké uživatelské rozhraní, zkuste přesouvat okna tak, aby se na obrázku zobrazovala jenom ta důležitá část.
  3. Pokud zahrnete uživatelské rozhraní snímku obrazovky, zobrazí se jenom důležité části. Když třeba mluvíte o tlačítkách na panelu nástrojů, vytvořte malý obrázek, který zobrazuje důležitá tlačítka panelu nástrojů, ale vyloučí všechno kolem něj.
  4. Používejte jenom obrázky, které se snadno reprodukují. To znamená, že značky ani zvýraznění na snímky obrazovky nevybarvujte. Zaprvé neexistují žádná konzistentní pravidla, jak by tato pravidla měla vypadat. Za druhé, reprodukování takového snímku obrazovky je další úsilí. Místo toho popište důležité části textu. Toto pravidlo má výjimky, ale jsou vzácné.
  5. Samozřejmě, je mnohem větší úsilí znovu vytvořit animovaný GIF. Počítejte s tím, že bude zodpovědný za to, že ho znovu vytvoříte až do konce času, nebo očekáváte, že ho lidé vyhodí, pokud tento čas nechtějí strávit.
  6. Ponechte počet obrázků v článku nízký. Často je dobrou metodou vytvořit jeden celkový snímek obrazovky některého nástroje, který zobrazuje všechno a pak popíše zbytek textu. V případě potřeby tak můžete snímek obrazovky snadno nahradit.

Některé další aspekty:

  • Uživatelské rozhraní editoru pro snímky obrazovky by mělo používat světle šedý editor motivu, protože všichni uživatelé nemají přístup k tmavému motivu a chtěli bychom zachovat co nejkonzistence.
  • Výchozí šířka obrázku je 500 pixelů, protože se dobře zobrazuje na většině monitorů. Nepokoušejte se od něj příliš odlišovat. Šířka 800 pixelů by měla být maximální.
  • Pro snímky obrazovky s uživatelským rozhraním použijte PNG.
  • Pro snímky obrazovky s 3D zobrazením použijte skupiny PNG nebo JPG. Upřednostněte kvalitu oproti poměru komprese.

Seznam vlastností komponenty

Při zdokumentování seznamu vlastností zvýrazněte název vlastnosti tučným písmem, potom konce řádků a běžný text, který je popisuje. Nepoužívejte dílčí kapitoly ani seznamy s odrážkami.

Nezapomeňte také dokončit všechny věty tečkou.

Kontrolní seznam pro dokončení stránky

  1. Ujistěte se, že byly dodrženy pokyny k tomuto dokumentu.
  2. Projděte strukturu dokumentu a podívejte se, jestli se nový dokument může zmínit v části Viz také na jiných stránkách.
  3. Pokud je k dispozici, požádejte někoho, kdo má znalosti o kontrole pravopisu tématu, stránku s informacemi o technické správnosti.
  4. Požádejte někoho, aby si stránku pro kontrolu pravopisu a formátování přečetl. Může to být někdo, kdo není známý v tématu, což je také vhodné získat zpětnou vazbu o tom, jak je dokumentace srozumitelná.

Zdrojová dokumentace

Dokumentace k rozhraní API se automaticky vygeneruje ze zdrojových souborů MRTK. Aby se to usnadnilo, musí zdrojové soubory obsahovat následující:

Kromě výše uvedeného by měl být kód dobře okomentován, aby umožňoval údržbu, opravy chyb a snadné přizpůsobení.

Class, struct, enum summary blocks

Pokud je třída, struktura nebo výčtu přidána do MRTK, musí být jeho účel popsán. Jde o formu souhrnného bloku nad třídou.

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

Pokud existují nějaké závislosti na úrovni třídy, měly by být zdokumentované v bloku poznámek bezprostředně pod souhrnem.

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

Žádosti o přijetí změn odeslané bez souhrnů tříd, struktur nebo výčtů nebudou schváleny.

Property, method, event summary blocks

Vlastnosti, metody a události (PME) a pole se dají zdokumentovat pomocí souhrnných bloků bez ohledu na viditelnost kódu (veřejné, soukromé, chráněné a interní). Nástroj pro generování dokumentace zodpovídá za filtrování a publikování pouze veřejných a chráněných funkcí.

POZNÁMKA: Souhrnný blok není vyžadován pro metody Unity (např. Vzhůru, Spustit, Aktualizovat).

K schválení žádosti o přijetí změn se vyžaduje dokumentace k PME.

V rámci souhrnného bloku PME se vyžaduje význam a účel parametrů a vrácených dat.

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

Úvodní verze funkcí a závislosti

V rámci souhrnné dokumentace k rozhraní API by měly být v bloku poznámek zdokumentované informace týkající se verze MRTK, ve které byla funkce zavedena, a všechny závislosti.

Závislosti by měly zahrnovat rozšíření a/nebo závislosti platformy.

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

Serializovaná pole

Je vhodné použít atribut popisu Unity k poskytnutí dokumentace modulu runtime pro pole skriptu v inspektoru.

Aby byly možnosti konfigurace zahrnuté do dokumentace k rozhraní API, musí skripty obsahovat alespoň obsah popisu v souhrnném bloku.

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

Hodnoty výčtu

Při definování a výčtu musí kód také zdokumentovat význam hodnot výčtu pomocí souhrnného bloku. Bloky poznámek lze volitelně použít k poskytnutí dalších podrobností k vylepšení porozumění.

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

Dokumentace s postupy

Mnoho uživatelů sady nástrojů Mixed Reality nemusí potřebovat používat dokumentaci k rozhraní API. Tito uživatelé budou využívat naše předem připravené opakovaně použitelné předfaby a skripty k vytvoření svých prostředí.

Každá oblast funkcí bude obsahovat jeden nebo více souborů Markdownu (.md), které popisují poměrně vysokou úroveň, co je k dispozici. V závislosti na velikosti a/nebo složitosti dané oblasti funkcí může být potřeba další soubory až na jednu zadanou funkci.

Při přidání funkce (nebo změně využití) musí být k dispozici dokumentace k přehledu.

V rámci této dokumentace by měly být k dispozici části s postupy, včetně ilustrací, které zákazníkům pomůžou začít s novou funkcí nebo konceptem.

Dokumentace k návrhu

Hybridní realita poskytuje příležitost vytvářet zcela nové světy. Součástí je pravděpodobně vytvoření vlastních prostředků pro použití s MRTK. Aby to bylo pro zákazníky co nejtřeknější, měly by komponenty poskytnout dokumentaci k návrhu popisující veškeré formátování nebo jiné požadavky na umělecké prostředky.

Některé příklady, kde může být užitečná dokumentace k návrhu:

  • Modely kurzoru
  • Vizualizace prostorového mapování
  • Soubory zvukového efektu

Tento typ dokumentace se důrazně doporučuje a může být požadován jako součást kontroly žádostí o přijetí změn.

To se může nebo nemusí lišit od doporučení k návrhu na webu MS Developer.

Poznámky k výkonu

Některé důležité funkce mají náklady na výkon. Tento kód bude často velmi záviset na tom, jak se konfigurují.

Příklad:

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.

Poznámky k výkonu se doporučují pro komponenty náročné na procesor nebo GPU a můžou být požadovány jako součást kontroly žádostí o přijetí změn. Všechny příslušné poznámky k výkonu se zahrnou do rozhraní API a přehledové dokumentace.

Změny způsobující chyby

Dokumentace k zásadním změnám se skládá ze souboru nejvyšší úrovně, který odkazuje na jednotlivé breaking-changes.md jednotlivých oblastí funkcí.

Oblast funkcí breaking-changes.md soubory obsahují seznam všech známých zásadních změn pro danou verzi a historii zásadních změn z minulých verzí.

Příklad:

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

Informace obsažené v breaking-changes.md úrovni funkcí se budou agregovat do poznámek k verzi pro každou novou verzi MRTK.

Všechny zásadní změny, které jsou součástí změny , musí být zdokumentované jako součást žádosti o přijetí změn.

Nástroje pro úpravy MarkDownu

Visual Studio Code je skvělý nástroj pro úpravy souborů markdownu, které jsou součástí dokumentace MRTK.

Při psaní dokumentace se také důrazně doporučuje nainstalovat následující dvě rozšíření:

  • Rozšíření Docs Markdown pro Visual Studio Code – Pomocí alt+M otevřete nabídku možností vytváření obsahu na webu Docs.

  • Kontrola pravopisu kódu – chybně napsaná slova budou podtržená; Klikněte pravým tlačítkem myši na chybně napsané slovo a změňte ho nebo ho uložte do slovníku.

Obě tyto sady jsou zabalené v balíčku Microsoftu publikovaném na webu Docs Authoring Pack.

Viz také