Condividi tramite

Linee guida per la documentazione - MRTK2

MRTK

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

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

Funzionalità e markup

Questa sezione descrive le funzionalità necessarie di frequente. Per vedere come funzionano, esaminare il codice sorgente della pagina.

  1. Elenchi numerato
    1. Elenchi numerato annidati con almeno 3 spazi vuoti iniziali
    2. Il numero effettivo nel codice è irrilevante; l'analisi si occuperà di impostare il numero di articolo corretto.
  • Elenchi di punti elenco
    • Elenchi di punti elenco annidati
  • Testo in grassetto con **doppio asterisco**
  • testo corsivo con _underscore_ o *asterisco singolo*
  • Testo highlighted as code all'interno di una frase 'using backquotes'
  • Collegamenti alle linee guida della documentazione di MRTK per le pagine di documentazione
  • Collegamenti agli ancoraggi all'interno di una pagina; gli ancoraggi si formano sostituendo spazi con trattini e convertendo in minuscole

Per gli esempi di codice vengono usati i blocchi con tre backticks ''' e viene specificato 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.

TODO

Evitare l'uso di TODO nella documentazione, perché nel tempo questi TODO (come il codice TODOs) tendono ad accumularsi e informazioni su come devono essere aggiornati e sul motivo per cui si perdono.

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

  1. Creare un nuovo problema in Github che descrive il contesto sottostante todo e fornire uno sfondo sufficiente 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: Un breve sfocatura sul problema...>

Sezioni evidenziate

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

Nota

Esempio di nota

Avviso

Esempio di avviso

Importante

Esempio di commento importante

Layout di pagina

Introduzione

La parte subito dopo il titolo del capitolo principale dovrebbe servire come breve introduzione di cosa tratta il capitolo. Non renderlo troppo lungo, ma aggiungere i titoli secondari. Questi consentono di collegarsi alle sezioni e possono essere salvati come segnalibri.

Corpo principale

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

Mini sezioni

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

Sezione 'Vedere anche'

La maggior parte delle pagine deve terminare con un capitolo denominato Vedere anche. Questo capitolo è semplicemente un elenco puntato di collegamenti a pagine correlate a questo argomento. Questi collegamenti possono essere visualizzati anche all'interno del testo della pagina, se necessario, ma non è necessario. Analogamente, il testo della pagina può contenere collegamenti a pagine non correlate all'argomento principale, che non devono essere incluse nell'elenco Vedere anche . Vedere il capitolo ''Vedi anche'' di questa pagina come esempio per la scelta dei collegamenti.

Sommario

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 nella navigazione della documentazione per sviluppatori. Può essere presente un file toc per ogni sottocartella nella cartella della documentazione che può essere collegato a qualsiasi file toc esistente per aggiungerlo come sottosezione alla parte corrispondente dello spostamento.

Stile

Stile di scrittura

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

  1. Non cercare di essere (eccessivamente) divertente.
  2. Non scrivere mai 'I'
  3. Evitare "noi". In genere è possibile riformularlo facilmente usando "MRTK". Esempio: "supportiamo questa funzionalità" -> "MRTK supporta questa funzionalità" o "sono supportate le funzionalità seguenti ...".
  4. Allo stesso modo, cercare di evitare 'tu'. Esempio: "Con questa semplice modifica lo shader diventa configurabile!" -> "Gli shader possono essere configurati con poco sforzo".
  5. Non usare "frasi sloppy".
  6. Evitare di sembrare eccessivamente eccitato, non abbiamo bisogno di vendere nulla.
  7. Allo stesso modo, evitare di essere eccessivamente drammatico. I segni esclamativi sono raramente necessari.

Capitalizzazione

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

Enfasi ed evidenziazione

Esistono due modi per enfatizzare o evidenziare le parole, rendendole grasse o in corsivo. L'effetto del testo in grassetto è che il testo in grassetto si sporge e quindi può essere facilmente notato durante lo scorrimento di un pezzo di testo o anche solo lo scorrimento su una pagina. Il grassetto è ideale per evidenziare le frasi che le persone devono ricordare. Tuttavia, usare il testo in grassetto raramente, perché in genere è fonte di distrazione.

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

Analogamente, quando un nome di file, un percorso o una voce di menu viene menzionato nel testo, preferiscono renderlo corsivo per raggrupparlo logicamente, senza distrarsi.

In generale, provare a evitare l'evidenziazione del testo non necessaria. 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.

Voci di menu di menzione

Quando si menziona una voce di menu su cui un utente deve fare clic, la convenzione corrente è: Project > Files > Create > Leaf

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

Preferire i collegamenti incorporati in una frase:

Evitare i 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 gli screenshot con parsimonia. La gestione delle immagini nella documentazione è molto lavoro, le piccole modifiche dell'interfaccia utente possono rendere obsoleti molti screenshot. Le regole seguenti ridurranno il lavoro di manutenzione:

  1. Non usare screenshot per elementi che possono essere descritti nel testo. In particolare, non fare mai screenshot di una griglia di proprietà al solo 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, crea uno screenshot del riquadro di visualizzazione, ma escludi qualsiasi interfaccia utente che lo circonda. Se si visualizza un'interfaccia utente, provare a spostare le finestre in modo che solo la parte importante sia presente 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 ciò che lo circonda.
  4. Usare solo immagini facili da riprodurre. Ciò significa che non disegnare marcatori o evidenziazioni negli 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 per 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 trascorrere quel tempo.
  6. Mantenere basso il numero di immagini in un articolo. Spesso un buon metodo consiste nel creare uno screenshot complessivo di uno strumento, che mostra tutto e quindi descrivere il resto nel testo. In questo modo è facile sostituire lo screenshot quando necessario.

Alcuni altri aspetti:

  • L'interfaccia utente dell'editor per gli screenshot deve usare l'editor di temi grigio chiaro perché non tutti gli utenti hanno accesso al tema scuro e vorremmo mantenere le cose il più coerenti possibile.
  • La larghezza predefinita dell'immagine è di 500 pixel, in quanto viene visualizzata correttamente nella maggior parte dei monitor. Cercate di non deviare troppo da esso. La larghezza massima deve essere di 800 pixel.
  • Usare PNG per gli screenshot dell'interfaccia utente.
  • Usare PNG o JPG per gli screenshot del viewport 3D. Preferire la qualità 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 usare sotto-capitoli o 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 può essere menzionato nella sezione Vedere anche di altre pagine.
  3. Se disponibile, chiedere a un utente con conoscenza dell'argomento di leggere la pagina per verificarne la correttezza tecnica.
  4. Fare in modo che qualcuno legga la pagina per stile e formattazione. Questo può essere qualcuno che non ha familiarità con l'argomento, che è anche una buona idea per ottenere commenti e suggerimenti su quanto sia comprensibile la documentazione.

Documentazione di origine

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

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

Blocchi di riepilogo di classi, struct e enum

Se si aggiunge una classe, uno struct o un'enumerazione a MRTK, è necessario descriverne lo scopo. Questa operazione assume 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 di 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 enumeazioni non verranno approvate.

Blocchi di riepilogo di proprietà, metodo e eventi

Proprietà, metodi ed eventi (PME) e 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: Awake, Start, Update).

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

Come parte di un blocco di riepilogo PME, sono necessari 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 e dipendenze dell'introduzione alla funzionalità

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

Le dipendenze devono includere estensioni e/o dipendenze 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.

In modo che le opzioni di configurazione siano 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

Durante la definizione e l'enumerazione, il codice deve anche documentare il significato dei valori di enumerazione usando un blocco di riepilogo. I blocchi note 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 delle procedura

Molti utenti di Realtà mista Toolkit potrebbero non dover usare la documentazione dell'API. Questi utenti sfrutteranno 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 piuttosto elevato, ciò che viene fornito. A seconda delle dimensioni e/o della complessità di una determinata area di funzionalità, potrebbero essere necessari file aggiuntivi, fino a un massimo di uno per ogni funzionalità fornita.

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

Come parte di questa documentazione, è necessario fornire sezioni dettagliate, incluse le illustrazioni, per aiutare i clienti che non hanno a che fare con una funzionalità o un concetto per iniziare.

Documentazione di progettazione

Realtà mista offre l'opportunità di creare mondi completamente nuovi. Una parte di questa operazione potrebbe comportare la creazione di asset personalizzati da usare con MRTK. Per rendere questa operazione il più possibile priva di problemi per i clienti, i componenti devono fornire la documentazione di progettazione che descrive qualsiasi formattazione o altri requisiti per gli asset artistici.

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

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

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

Questa operazione può essere diversa o meno dalla raccomandazione di progettazione nel sito per sviluppatori DI MICROSOFT

Note sulle prestazioni

Alcune funzionalità importanti hanno un costo per le prestazioni. Spesso questo codice dipende molto da come vengono configurati.

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 i componenti cpu e/o GPU pesanti e possono essere richieste come parte di una verifica della richiesta pull. Tutte le note sulle prestazioni applicabili devono essere incluse nell'API e nella documentazione di panoramica.

Modifiche di rilievo

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 di 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 di rilievo delle 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.

Tutte le 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 è un ottimo strumento per modificare i file markdown che fanno parte della documentazione di MRTK.

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

  • Estensione Markdown docs per Visual Studio Code: usare ALT+M per visualizzare un menu di opzioni di creazione di documenti.

  • Controllo 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 sono inclusi nel pacchetto Docs Authoring Pack pubblicato da Microsoft.

Vedere anche