Instructions de documentation — MRTK2

  • Article
MRTK

Ce document décrit les directives et les normes relatives à Mixed Reality Toolkit (MRTK). Il s’agit d’une introduction aux aspects techniques de la rédaction et de la génération de documentation, afin de mettre en évidence les pièges courants et de décrire le style d’écriture recommandé.

La page elle-même est censée servir d’exemple, elle utilise donc le style prévu et les fonctionnalités de balisage les plus courantes de la documentation.

Fonctionnalités et balisage

Cette section décrit les fonctionnalités fréquemment nécessaires. Pour voir comment ils fonctionnent, examinez le code source de la page.

  1. Listes numérotées
    1. Listes numérotées imbriquées avec au moins 3 espaces vides de début
    2. Le nombre réel dans le code n’est pas pertinent; L’analyse se charge de définir le numéro d’élément correct.
  • Listes à puces
    • Listes à puces imbriquées
  • Texte en gras avec **double astérisque**
  • texte italique avec _trait de soulignement_ ou *astérisque unique*
  • Texte highlighted as code dans une phrase « using backquotes »
  • Liens vers les instructions de documentation MRTK sur les pages de documents
  • Liens vers des ancres dans une page ; Les ancres sont formées en remplaçant les espaces par des tirets et en les convertissant en minuscules

Pour les exemples de code, nous utilisons les blocs avec trois backticks « » et spécifions csharp comme langage pour la mise en surbrillance de la syntaxe :

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

Quand vous mentionnez du code dans une phrase use a single backtick.

Todos

Évitez d’utiliser des TODO dans les documents, car au fil du temps, ces OBJETS TODO (comme les TODO de code) ont tendance à s’accumuler et à des informations sur la façon dont ils doivent être mis à jour et la raison pour laquelle ils sont perdus.

S’il est absolument nécessaire d’ajouter un TODO, procédez comme suit :

  1. Créez un nouveau problème sur Github en décrivant le contexte derrière le TODO et fournissez suffisamment d’arrière-plan pour qu’un autre contributeur puisse comprendre, puis résoudre le TODO.
  2. Référencez l’URL du problème dans la tâche à effectuer dans la documentation.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Un bref flou sur la question -->

Sections mises en surbrillance

Pour mettre en surbrillance des points spécifiques au lecteur, utilisez > [! REMARQUE] , > [! AVERTISSEMENT] , et > [! IMPORTANT] pour produire les styles suivants. Il est recommandé d’utiliser des notes pour les points généraux et les points d’avertissement/importants uniquement pour des cas spécifiques pertinents.

Notes

Exemple de note

Avertissement

Exemple d’avertissement

Important

Exemple de commentaire important

Mise en page

Introduction

La partie juste après le titre du chapitre main doit servir de brève introduction à ce qu’est le chapitre. Ne faites pas cela trop long, mais ajoutez plutôt des sous-titres. Celles-ci permettent d’établir un lien vers des sections et peuvent être enregistrées en tant que signets.

Corps principal

Utilisez des titres à deux et trois niveaux pour structurer le reste.

Mini-sections

Utilisez une ligne de texte en gras pour les blocs qui doivent se démarquer. Nous pourrions remplacer cela par des titres à quatre niveaux à un moment donné.

Section « Voir aussi »

La plupart des pages doivent se terminer par un chapitre appelé Voir aussi. Ce chapitre est simplement une liste à puces de liens vers des pages liées à ce sujet. Ces liens peuvent également apparaître dans le texte de la page le cas échéant, mais cela n’est pas obligatoire. De même, le texte de la page peut contenir des liens vers des pages qui ne sont pas liées à la rubrique main; ceux-ci ne doivent pas être inclus dans la liste Voir aussi. Consultez le chapitre « Voir aussi » de cette page comme exemple pour le choix des liens.

Table des matières

Les fichiers Toc sont utilisés pour générer les barres de navigation dans la documentation mrTK github.io. Chaque fois qu’un nouveau fichier de documentation est ajouté, assurez-vous qu’il existe une entrée pour ce fichier dans l’un des fichiers toc.yml du dossier de documentation. Seuls les articles répertoriés dans les fichiers toc s’affichent dans la navigation de la documentation du développeur. Il peut y avoir un fichier toc pour chaque sous-dossier dans le dossier de documentation, qui peut être lié à n’importe quel fichier toc existant pour l’ajouter en tant que sous-section à la partie correspondante de la navigation.

Style

Style d’écriture

Règle générale : Essayez de paraître professionnel. Cela signifie généralement éviter un « ton conversationnel ». Essayez également d’éviter l’hyperbole et le sensationnalisme.

  1. N’essayez pas d’être (trop) drôle.
  2. N’écrivez jamais « I »
  3. Évitez « nous ». Cela peut généralement être reformulé facilement, à l’aide de « MRTK » à la place. Exemple : « nous prenons en charge cette fonctionnalité » :> « MRTK prend en charge cette fonctionnalité » ou « les fonctionnalités suivantes sont prises en charge ... ».
  4. De même, essayez d’éviter « vous ». Exemple : « Avec cette simple modification, votre nuanceur devient configurable ! » -> « Les nuanceurs peuvent être configurés avec peu d’effort ».
  5. N’utilisez pas de « phrases bâclées ».
  6. Évitez de paraître trop excité, nous n’avons pas besoin de vendre quoi que ce soit.
  7. De même, évitez d’être trop dramatique. Les points d’exclamation sont rarement nécessaires.

Mise en majuscules

  • Utilisez la casse de phrase pour les titres. Ie. mettre en majuscules la première lettre et les noms, mais rien d’autre.
  • Utilisez l’anglais standard pour tout le reste. Cela signifie qu’il ne faut pas mettre en majuscules les mots arbitraires, même s’ils ont une signification particulière dans ce contexte. Préférez le texte italique pour mettre en surbrillance certains mots, voir ci-dessous.
  • Lorsqu’un lien est incorporé dans une phrase (méthode par défaut), le nom de chapitre standard utilise toujours des lettres majuscules, ce qui enfreint la règle de l’absence de mise en majuscules arbitraire à l’intérieur du texte. Par conséquent, utilisez un nom de lien personnalisé pour corriger la mise en majuscules. À titre d’exemple, voici un lien vers la documentation du contrôle des limites .
  • Mettre en majuscule les noms, par exemple Unity.
  • Ne pas mettre en majuscule « éditeur » lors de l’écriture de l’éditeur Unity.

Accentuation et mise en surbrillance

Il existe deux façons de mettre en évidence ou de mettre en évidence des mots, les rendre gras ou italiques. L’effet du texte en gras est que le texte en gras se maintient et peut donc facilement être remarqué lors de l’écrémation d’un morceau de texte ou même du simple défilement sur une page. L’gras est idéal pour mettre en évidence les expressions dont les gens doivent se souvenir. Toutefois, utilisez rarement du texte en gras, car il est généralement distrayant.

Souvent, on veut « regrouper » quelque chose qui appartient logiquement ensemble ou mettre en évidence un terme spécifique, car il a une signification particulière. De telles choses n’ont pas besoin de se démarquer du texte global. Utilisez du texte italique comme méthode légère pour mettre en surbrillance quelque chose.

De même, lorsqu’un nom de fichier, un chemin d’accès ou une entrée de menu est mentionné dans le texte, préférez le mettre en italique pour le regrouper logiquement, sans être distrait.

En général, essayez d’éviter la mise en surbrillance inutile du texte. Les termes spéciaux peuvent être mis en surbrillance une seule fois pour sensibiliser le lecteur, ne pas répéter cette mise en surbrillance dans tout le texte, quand cela ne sert plus à rien et ne fait que distraire.

Mention des entrées de menu

Quand vous mentionnez une entrée de menu sur laquelle un utilisateur doit cliquer, la convention actuelle est : Project > Files > Create > Leaf

Insérez autant de liens utiles vers d’autres pages que possible, mais chaque lien une seule fois. Supposons qu’un lecteur clique sur chaque lien de la page et qu’il soit ennuyeux si la même page s’ouvre 20 fois.

Préférez les liens incorporés dans une phrase :

Évitez les liens externes, ils peuvent devenir obsolètes ou contenir du contenu protégé par des droits d’auteur.

Lorsque vous ajoutez un lien, déterminez s’il doit également être répertorié dans la section Voir aussi . De même, case activée si un lien vers la nouvelle page doit être ajouté à la page liée.

Images / captures d’écran

Utilisez les captures d’écran avec parcimonie. La maintenance des images dans la documentation est un travail important. De petites modifications de l’interface utilisateur peuvent rendre obsolètes de nombreuses captures d’écran. Les règles suivantes réduisent l’effort de maintenance :

  1. N’utilisez pas de captures d’écran pour les éléments qui peuvent être décrits dans du texte. En particulier, ne capturez jamais une grille de propriétés dans le seul but d’afficher les noms et les valeurs des propriétés.
  2. N’incluez pas dans une capture d’écran des éléments qui ne sont pas pertinents par rapport à ce qui est affiché. Par instance, lorsqu’un effet de rendu est affiché, effectuez une capture d’écran de la fenêtre d’affichage, mais excluez toute interface utilisateur qui l’entoure. Montrant une certaine interface utilisateur, essayez de déplacer les fenêtres de sorte que seule cette partie importante se trouve dans l’image.
  3. Lorsque vous incluez l’interface utilisateur de capture d’écran, affichez uniquement les parties importantes. Par exemple, lorsque vous parlez de boutons dans une barre d’outils, créez une petite image qui montre les boutons importants de la barre d’outils, mais excluez tout ce qui l’entoure.
  4. Utilisez uniquement des images faciles à reproduire. Cela signifie qu’il ne faut pas peindre les marqueurs ou les surbrillances dans des captures d’écran. Tout d’abord, il n’y a pas de règles cohérentes à quoi cela doit ressembler, de toute façon. Deuxièmement, la reproduction d’une telle capture d’écran est un effort supplémentaire. Au lieu de cela, décrivez les parties importantes du texte. Il existe des exceptions à cette règle, mais elles sont rares.
  5. Évidemment, il est beaucoup plus difficile de recréer un GIF animé. Attendez-vous à être responsable de le recréer jusqu’à la fin des temps, ou attendez-vous à ce que les gens le jettent, s’ils ne veulent pas passer ce temps.
  6. Limitez le nombre d’images d’un article. Souvent, une bonne méthode consiste à effectuer une capture d’écran globale d’un outil, qui montre tout, puis à décrire le reste dans du texte. Cela facilite le remplacement de la capture d’écran si nécessaire.

D’autres aspects sont les suivants :

  • L’interface utilisateur de l’éditeur pour les captures d’écran doit utiliser l’éditeur de thème gris clair, car tous les utilisateurs n’ont pas accès au thème sombre et nous aimerions garder les choses aussi cohérentes que possible.
  • La largeur d’image par défaut est de 500 pixels, car elle s’affiche bien sur la plupart des moniteurs. Essayez de ne pas trop en dévier. La largeur maximale doit être de 800 pixels.
  • Utilisez des groupes de sécurité réseau pour les captures d’écran de l’interface utilisateur.
  • Utilisez des groupes de sécurité réseau ou DESG pour les captures d’écran de fenêtre d’affichage 3D. Préférez la qualité au taux de compression.

Liste des propriétés du composant

Lorsque vous documentez une liste de propriétés, utilisez du texte en gras pour mettre en surbrillance le nom de la propriété, puis des sauts de ligne et du texte normal pour les décrire. N’utilisez pas de sous-chapitres ou de listes à puces.

En outre, n’oubliez pas de terminer toutes les phrases avec un point.

Liste de contrôle de saisie semi-automatique des pages

  1. Vérifiez que les instructions de ce document ont été suivies.
  2. Parcourez la structure du document et vérifiez si le nouveau document peut être mentionné sous la section Voir aussi d’autres pages.
  3. S’il est disponible, faites en sorte que quelqu’un ayant une connaissance de la rubrique vérifie l’exactitude technique de la page.
  4. Demander à quelqu’un de lire la page pour le style et la mise en forme. Il peut s’agir d’une personne qui ne connaît pas le sujet, ce qui est également une bonne idée d’obtenir des commentaires sur la compréhension de la documentation.

Documentation source

La documentation de l’API sera générée automatiquement à partir des fichiers sources MRTK. Pour faciliter cela, les fichiers sources doivent contenir les éléments suivants :

En plus de ce qui précède, le code doit être bien commenté pour permettre la maintenance, les correctifs de bogues et la facilité de personnalisation.

Blocs récapitulatives de classe, struct, enum

Si une classe, un struct ou un enum est ajouté au MRTK, son objectif doit être décrit. Il s’agit d’un bloc de synthèse au-dessus de la classe .

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

S’il existe des dépendances au niveau de la classe, elles doivent être documentées dans un bloc de remarques, juste en dessous du résumé.

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

Les demandes de tirage envoyées sans résumé pour les classes, les structures ou les énumérations ne seront pas approuvées.

Blocs de propriétés, de méthode et de résumé d’événements

Les propriétés, les méthodes et les événements (PME) ainsi que les champs doivent être documentés avec des blocs de synthèse, quelle que soit la visibilité du code (public, privé, protégé et interne). L’outil de génération de documentation est chargé de filtrer et de publier uniquement les fonctionnalités publiques et protégées.

REMARQUE : Un bloc de synthèse n’est pas requis pour les méthodes Unity (par exemple, Awake, Start, Update).

La documentation PME est requise pour qu’une demande de tirage soit approuvée.

Dans le cadre d’un bloc de synthèse PME, la signification et l’objectif des paramètres et des données retournées sont nécessaires.

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

Version d’introduction des fonctionnalités et dépendances

Dans la documentation récapitulative de l’API, les informations relatives à la version MRTK dans laquelle la fonctionnalité a été introduite et à toutes les dépendances doivent être documentées dans un bloc de remarques.

Les dépendances doivent inclure les dépendances d’extension et/ou de plateforme.

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

Champs sérialisés

Il est recommandé d’utiliser l’attribut d’info-bulle d’Unity pour fournir une documentation d’exécution pour les champs d’un script dans l’inspecteur.

Pour que les options de configuration soient incluses dans la documentation de l’API, des scripts sont requis pour inclure au moins le contenu de l’info-bulle dans un bloc récapitulatif.

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

Valeurs d’énumération

Lors de la définition et de l’énumération, le code doit également documenter la signification des valeurs d’énumération à l’aide d’un bloc de synthèse. Les blocs de remarques peuvent éventuellement être utilisés pour fournir des détails supplémentaires afin d’améliorer la compréhension.

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

Documentation de procédures

De nombreux utilisateurs de Mixed Reality Toolkit n’ont peut-être pas besoin d’utiliser la documentation de l’API. Ces utilisateurs tireront parti de nos préfabriqués et scripts prédéfinis et réutilisables pour créer leurs expériences.

Chaque zone de fonctionnalité contient un ou plusieurs fichiers markdown (.md) qui décrivent à un niveau assez élevé ce qui est fourni. Selon la taille et/ou la complexité d’une zone de fonctionnalité donnée, il peut y avoir besoin de fichiers supplémentaires, jusqu’à un par fonctionnalité fournie.

Lorsqu’une fonctionnalité est ajoutée (ou que l’utilisation est modifiée), une documentation de vue d’ensemble doit être fournie.

Dans le cadre de cette documentation, des sections de procédure, y compris des illustrations, doivent être fournies pour aider les clients qui commencent à utiliser une fonctionnalité ou un concept dans la prise en main.

Documentation de conception

Mixed Reality offre la possibilité de créer des mondes entièrement nouveaux. Une partie de cela est susceptible d’impliquer la création de ressources personnalisées à utiliser avec MRTK. Pour que cela soit le plus libre possible pour les clients, les composants doivent fournir une documentation de conception décrivant toute mise en forme ou d’autres exigences pour les ressources artistiques.

Voici quelques exemples où la documentation de conception peut être utile :

  • Modèles de curseur
  • Visualisations de mappage spatial
  • Fichiers d’effets sonores

Ce type de documentation est fortement recommandé et peut être demandé dans le cadre d’un révision de demande de tirage.

Cela peut être différent ou non de la recommandation de conception sur le site du développeur MS

Notes sur les performances

Certaines fonctionnalités importantes ont un coût de performances. Souvent, ce code dépend de la façon dont ils sont configurés.

Par exemple :

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.

Les notes de performances sont recommandées pour les composants lourds processeur et/ou GPU et peuvent être demandées dans le cadre d’une révision de demande de tirage. Toutes les notes de performances applicables doivent être incluses dans la documentation d’API et de vue d’ensemble.

Changements cassants

La documentation sur les changements cassants consiste en un fichier de niveau supérieur qui établit des liens vers les breaking-changes.md individuels de chaque zone de fonctionnalité.

La zone de fonctionnalité breaking-changes.md fichiers doivent contenir la liste de toutes les modifications cassants connues pour une version donnée , ainsi que l’historique des modifications cassants par rapport aux versions précédentes.

Par exemple :

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

Les informations contenues dans les fichiers de niveau de fonctionnalité breaking-changes.md sont agrégées aux notes de publication de chaque nouvelle version MRTK.

Toutes les modifications cassants qui font partie d’une modification doivent être documentées dans le cadre d’une demande de tirage.

Outils de modification de MarkDown

Visual Studio Code est un excellent outil pour modifier des fichiers Markdown qui font partie de la documentation de MRTK.

Lors de l’écriture de la documentation, l’installation des deux extensions suivantes est également fortement recommandée :

  • Extension Docs Markdown pour Visual Studio Code : utilisez Alt+M pour afficher un menu d’options de création de documents.

  • Vérificateur orthographique de code : les mots mal orthographiés sont soulignés. Cliquez avec le bouton droit sur un mot mal orthographié pour le modifier ou ou l'enregistrer dans le dictionnaire.

Ces deux éléments sont fournis dans le pack de création Docs publié par Microsoft.

Voir aussi