Linee guida per la documentazione - MRTK2

  • Articolo
MRTK

Questo documento descrive le linee guida e gli standard della documentazione per Realtà mista Toolkit (MRTK). In questo modo viene fornita un'introduzione agli aspetti tecnici di scrittura e generazione della documentazione, per evidenziare le insidie comuni e descrivere lo stile di scrittura consigliato.

La pagina stessa dovrebbe fungere da esempio, pertanto usa lo stile previsto e le funzionalità di markup più comuni della documentazione.

Funzionalità e markup

In questa sezione vengono descritte le funzionalità necessarie di frequente. Per vedere come funzionano, esaminare il codice sorgente della pagina.

  1. Elenchi numerati
    1. Elenchi numerati annidati con almeno 3 spazi vuoti iniziali
    2. Il numero effettivo nel codice è irrilevante; l'analisi si occuperà dell'impostazione del numero di elemento corretto.

Per gli esempi di codice vengono usati i blocchi con tre backticks ''' e si specifica csharp come linguaggio per l'evidenziazione della sintassi:

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

Quando si menziona il codice all'interno di una frase use a single backtick.

Todos

Evitare di usare TODOs nella documentazione, poiché nel corso del tempo questi TODO (ad esempio toDO di codice) tendono ad accumulare e a ottenere informazioni su come devono essere aggiornati e perché vengono persi.

Se è assolutamente necessario aggiungere un TODO, seguire questa procedura:

  1. Segnalare un nuovo problema in GitHub che descrive il contesto sottostante toDO e fornire informazioni sufficienti per consentire a un altro collaboratore di comprendere e quindi risolvere il todo.
  2. Fare riferimento all'URL del problema nel todo nella documentazione.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: breve blurb sul problema ->

Sezioni evidenziate

Per evidenziare punti specifici per il lettore, usare > [! NOTA] , > [! AVVISO] , e > [! IMPORTANTE] per produrre gli stili seguenti. È consigliabile usare note per i punti generali e i punti di avviso/importanti solo per casi particolari rilevanti.

Nota

Esempio di nota

Avviso

Esempio di avviso

Importante

Esempio di un commento importante

Layout di pagina

Introduzione

La parte subito dopo il titolo del capitolo principale dovrebbe fungere da breve introduzione di ciò che riguarda il capitolo. Non rendere troppo lungo, invece aggiungere i titoli secondari. Questi consentono di collegarsi alle sezioni e possono essere salvati come segnalibri.

Corpo principale

Usare i titoli a due livelli e a tre livelli per strutturare il resto.

Mini sezioni

Usare una riga di testo in grassetto per i blocchi che devono distinguersi. A un certo punto potremmo sostituirlo con i titoli a quattro livelli.

Sezione 'Vedere anche'

La maggior parte delle pagine dovrebbe terminare con un capitolo denominato anche See. Questo capitolo è semplicemente un elenco puntato di collegamenti alle pagine correlate a questo argomento. Questi collegamenti possono essere visualizzati anche all'interno del testo della pagina, se appropriato, ma questo non è obbligatorio. Analogamente, il testo della pagina può contenere collegamenti a pagine non correlate all'argomento principale, che non devono essere incluse nell'elenco Vedere anche . Per informazioni sulla scelta dei collegamenti, vedere il capitolo ''Vedi anche'' di questa pagina .

Sommario (TOC)

I file toc vengono usati per generare le barre di spostamento nella documentazione di MRTK github.io. Ogni volta che viene aggiunto un nuovo file di documentazione, assicurarsi che sia presente una voce per tale file in uno dei file toc.yml della cartella della documentazione. Solo gli articoli elencati nei file toc verranno visualizzati nel riquadro di spostamento della documentazione per sviluppatori. Può essere presente un file toc per ogni sottocartella nella cartella della documentazione che può essere collegata a qualsiasi file toc esistente per aggiungerlo come sottosezione alla parte corrispondente dello spostamento.

Stile

Stile di scrittura

Regola generale: provare a suonare professionale. Ciò significa in genere evitare un "tono conversazionale". Cercare anche di evitare iperbole e sensazionalismo.

  1. Non cercare di essere (troppo) divertente.
  2. Non scrivere mai 'I'
  3. Evitare "noi". Questo può in genere essere riformulare facilmente, usando invece 'MRTK'. Esempio: "supportiamo questa funzionalità" -> "MRTK supporta questa funzionalità" o "sono supportate le funzionalità seguenti...".
  4. Analogamente, cercare di evitare "tu". Esempio: "Con questa semplice modifica lo shader diventa configurabile!" -> "Gli shader possono essere resi configurabili con poco sforzo".
  5. Non usare le frasi sloppy.
  6. Evitare di suonare eccessivamente eccitato, non abbiamo bisogno di vendere nulla.
  7. Analogamente, evita di essere eccessivamente drammatico. I segni esclamativi sono raramente necessari.

Uso delle maiuscole

  • Usare la distinzione tra maiuscole e minuscole per i titoli. Ie. in maiuscolo la prima lettera e i nomi, ma nient'altro.
  • Usa l'inglese normale per tutto il resto. Ciò significa che non maiuscolano parole arbitrarie, anche se contengono un significato speciale in tale contesto. Preferisce il corsivo per evidenziare determinate parole, vedere di seguito.
  • Quando un collegamento viene incorporato in una frase (che è il metodo preferito), il nome del capitolo standard usa sempre lettere maiuscole, interrompendo così la regola di nessuna maiuscola arbitraria all'interno del testo. Usare quindi un nome di collegamento personalizzato per correggere la combinazione di maiuscole e minuscole. Di seguito è riportato un collegamento alla documentazione del controllo dei limiti .
  • Assegnare maiuscole ai nomi, ad esempio Unity.
  • Non usare la maiuscola "editor" durante la scrittura dell'editor unity.

Enfasi ed evidenziazione

Esistono due modi per enfatizzare o evidenziare le parole, rendendole in grassetto o rendendole corsivo. L'effetto del testo in grassetto è che il testo in grassetto si attacca e quindi può essere facilmente notato mentre si ignora un testo o anche semplicemente scorrere su una pagina. Il grassetto è ideale per evidenziare frasi che le persone devono ricordare. Tuttavia, usare il testo in grassetto raramente, perché in genere è distratto.

Spesso si vuole "raggruppare" qualcosa che appartiene logicamente o evidenziare un termine specifico, perché ha un significato speciale. Queste cose non devono distinguersi dal testo complessivo. Usare il testo corsivo come metodo leggero per evidenziare un elemento.

Analogamente, quando un nome file, un percorso o una voce di menu viene menzionato nel testo, preferisce in corsivo raggrupparlo logicamente, senza distrarre.

In generale, provare a evitare l'evidenziazione del testo non necessaria. I termini speciali possono essere evidenziati una volta per rendere il lettore consapevole, non ripetere tale evidenziazione in tutto il testo, quando non serve più scopo e solo distrae.

Menzione delle voci di menu

Quando si indica una voce di menu che un utente deve fare clic, la convenzione corrente è: File di progetto >> Crea > foglia

Inserire il maggior numero possibile di collegamenti utili ad altre pagine, ma ogni collegamento una sola volta. Si supponga che un lettore faccia clic su ogni collegamento nella pagina e pensi a quanto sarebbe fastidioso, se la stessa pagina si apre 20 volte.

Preferisce i collegamenti incorporati in una frase:

Evitare collegamenti esterni, possono diventare obsoleti o contenere contenuti protetti da copyright.

Quando si aggiunge un collegamento, valutare se deve essere elencato anche nella sezione Vedere anche . Analogamente, controllare se è necessario aggiungere un collegamento alla nuova pagina alla pagina collegata.

Immagini/screenshot

Usare le schermate con moderazione. La gestione delle immagini nella documentazione è un sacco di lavoro, piccole modifiche all'interfaccia utente possono apportare molte schermate obsolete. Le regole seguenti ridurranno le attività di manutenzione:

  1. Non usare screenshot per gli elementi che possono essere descritti nel testo. In particolare, non screenshot mai di una griglia di proprietà per l'unico scopo di visualizzare i nomi e i valori delle proprietà.
  2. Non includere elementi in uno screenshot irrilevanti per ciò che viene visualizzato. Ad esempio, quando viene visualizzato un effetto di rendering, creare uno screenshot del riquadro di visualizzazione, ma escludere qualsiasi interfaccia utente. Mostrare un'interfaccia utente, provare a spostare le finestre in modo che solo quella parte importante si trova nell'immagine.
  3. Quando si include l'interfaccia utente dello screenshot, mostra solo le parti importanti. Ad esempio, quando si parla di pulsanti in una barra degli strumenti, creare una piccola immagine che mostra i pulsanti importanti della barra degli strumenti, ma escludere tutto intorno.
  4. Usare solo immagini facili da riprodurre. Ciò significa che non disegnare marcatori o evidenziazioni in screenshot. In primo luogo, non ci sono regole coerenti come dovrebbero apparire, comunque. In secondo luogo, la riproduzione di tale screenshot è un ulteriore sforzo. Descrivere invece le parti importanti nel testo. Esistono eccezioni a questa regola, ma sono rare.
  5. Ovviamente, è molto più sforzo ricreare una GIF animata. Aspettatevi di essere responsabili di ricrearlo fino alla fine del tempo o aspettatevi che le persone lo buttano fuori, se non vogliono dedicare quel tempo.
  6. Mantenere basso il numero di immagini in un articolo. Spesso un buon metodo consiste nel creare uno screenshot complessivo di alcuni strumenti, che mostra tutto e quindi descrivere il resto nel testo. In questo modo è facile sostituire lo screenshot quando necessario.

Altri aspetti:

  • L'interfaccia utente dell'editor per gli screenshot deve usare l'editor dei temi grigio chiaro, perché non tutti gli utenti hanno accesso al tema scuro e vogliamo mantenere le cose il più coerenti possibile.
  • La larghezza predefinita dell'immagine è di 500 pixel, perché viene visualizzata bene nella maggior parte dei monitor. Cerca di non deviare troppo da esso. La larghezza di 800 pixel deve essere massima.
  • Usare i PNG per gli screenshot dell'interfaccia utente.
  • Usare I GPN o IG per gli screenshot del viewport 3D. Preferire la qualità rispetto al rapporto di compressione.

Elenco delle proprietà dei componenti

Quando si documenta un elenco di proprietà, usare il testo in grassetto per evidenziare il nome della proprietà, quindi le interruzioni di riga e il testo normale per descriverli. Non utilizzare i capitoli secondari o gli elenchi di punti elenco.

Inoltre, non dimenticare di completare tutte le frasi con un punto.

Elenco di controllo per il completamento della pagina

  1. Assicurarsi che siano state seguite le linee guida di questo documento.
  2. Esplorare la struttura del documento e verificare se il nuovo documento potrebbe essere menzionato nella sezione Vedere anche altre pagine.
  3. Se disponibile, chiedere a un utente con conoscenza dell'argomento di leggere la pagina relativa alla correttezza tecnica.
  4. Chiedere a qualcuno di leggere la pagina per lo stile e la formattazione. Può trattarsi di un utente che non ha familiarità con l'argomento, che è anche una buona idea per ottenere commenti e suggerimenti su quanto comprensibile sia la documentazione.

Documentazione di origine

La documentazione dell'API verrà generata automaticamente dai file di origine MRTK. Per facilitare questa operazione, i file di origine devono contenere quanto segue:

Oltre a quanto sopra riportato, il codice deve essere ben commentato per consentire la manutenzione, le correzioni di bug e la facilità di personalizzazione.

Classe, struct, blocchi di riepilogo delle enumerazioni

Se una classe, uno struct o un'enumerazione viene aggiunta a MRTK, è necessario descriverne lo scopo. Si tratta di assumere la forma di un blocco di riepilogo sopra la classe .

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

Se sono presenti dipendenze a livello di classe, devono essere documentate in un blocco osservazioni, immediatamente sotto il riepilogo.

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

Le richieste pull inviate senza riepiloghi per classi, strutture o enumerazioni non verranno approvate.

Proprietà, metodo, blocchi di riepilogo degli eventi

Le proprietà, i metodi e gli eventi (PME) e i campi devono essere documentati con blocchi di riepilogo, indipendentemente dalla visibilità del codice (pubblica, privata, protetta e interna). Lo strumento di generazione della documentazione è responsabile del filtro e della pubblicazione solo delle funzionalità pubbliche e protette.

NOTA: non è necessario un blocco di riepilogo per i metodi Unity (ad esempio: Sveglio, Start, Aggiornamento).

La documentazione pmE è necessaria per l'approvazione di una richiesta pull.

Come parte di un blocco di riepilogo PME, è necessario il significato e lo scopo dei parametri e dei dati restituiti.

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

Versione introduttiva delle funzionalità e dipendenze

Come parte della documentazione di riepilogo dell'API, le informazioni relative alla versione MRTK in cui è stata introdotta la funzionalità e le eventuali dipendenze devono essere documentate in un blocco osservazioni.

Le dipendenze devono includere le dipendenze dell'estensione e/o della piattaforma.

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

Campi serializzati

È consigliabile usare l'attributo della descrizione comando di Unity per fornire la documentazione di runtime per i campi di uno script nel controllo.

Pertanto, le opzioni di configurazione sono incluse nella documentazione dell'API, gli script devono includere almeno il contenuto della descrizione comando in un blocco di riepilogo.

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

Valori di enumerazione

Quando si definisce ed enumerazione, il codice deve anche documentare il significato dei valori di enumerazione usando un blocco di riepilogo. I blocchi osservazioni possono essere usati facoltativamente per fornire dettagli aggiuntivi per migliorare la comprensione.

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

Documentazione pratica

Molti utenti di Realtà mista Toolkit potrebbero non dover usare la documentazione dell'API. Questi utenti sfruttano i prefab e gli script riutilizzabili predefiniti per creare le proprie esperienze.

Ogni area di funzionalità conterrà uno o più file markdown (con estensione md) che descrivono a un livello abbastanza elevato, cosa viene fornito. A seconda delle dimensioni e/o della complessità di una determinata area di funzionalità, potrebbero essere necessari file aggiuntivi, fino a uno per ogni funzionalità fornita.

Quando viene aggiunta una funzionalità (o l'utilizzo viene modificato), è necessario fornire la documentazione di panoramica.

Nell'ambito di questa documentazione, le sezioni sulle procedure, incluse le illustrazioni, devono essere fornite per assistere i clienti nuovi a una funzionalità o a un concetto per iniziare.

Documentazione sulla progettazione

Realtà mista offre l'opportunità di creare mondi completamente nuovi. Una parte di questa operazione prevede probabilmente la creazione di asset personalizzati da usare con MRTK. Per rendere questo il più possibile attrito per i clienti, i componenti devono fornire documentazione di progettazione che descrive qualsiasi formattazione o altri requisiti per le risorse artistiche.

Alcuni esempi in cui la documentazione di progettazione può essere utile:

  • Modelli di cursore
  • Visualizzazioni di mapping spaziale
  • File dell'effetto audio

Questo tipo di documentazione è fortemente consigliato e può essere richiesto come parte di una revisione della richiesta pull.

Questo può essere o meno diverso dalla raccomandazione di progettazione nel sito per sviluppatori MS

Note sulle prestazioni

Alcune funzionalità importanti sono a un costo delle prestazioni. Spesso questo codice dipende dalla modalità di configurazione.

Ad esempio:

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.

Le note sulle prestazioni sono consigliate per componenti con utilizzo elevato di CPU e/o GPU e possono essere richieste come parte di una revisione della richiesta pull. Eventuali note sulle prestazioni applicabili devono essere incluse nell'API e nella documentazione di panoramica.

Modifiche che causano un'interruzione

La documentazione relativa alle modifiche di rilievo consiste in un file di primo livello che collega i singoli breaking-changes.md di ogni area di funzionalità.

L'area delle funzionalità breaking-changes.md file deve contenere l'elenco di tutte le modifiche di rilievo note per una determinata versione , nonché la cronologia delle modifiche che causano interruzioni rispetto alle versioni precedenti.

Ad esempio:

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

Le informazioni contenute nel livello di funzionalità breaking-changes.md file verranno aggregate alle note sulla versione per ogni nuova versione di MRTK.

Eventuali modifiche di rilievo che fanno parte di una modifica devono essere documentate come parte di una richiesta pull.

Strumenti per la modifica di MarkDown

Visual Studio Code è uno strumento ideale per la modifica di file markdown che fanno parte della documentazione di MRTK.

Durante la scrittura della documentazione, è consigliabile installare anche le due estensioni seguenti:

  • Docs Markdown Extension for Visual Studio Code - Usare ALT+M per visualizzare un menu di opzioni di creazione dei documenti.

  • Correttore ortografico del codice: le parole con errori di ortografia verranno sottolineate; fare clic con il pulsante destro del mouse su una parola con errori di ortografia per modificarla o salvarla nel dizionario.

Entrambi questi pacchetti sono inclusi in Microsoft published Docs Authoring Pack.

Vedi anche