Recommandations en matière de documentation — MRTK2

MRTK

Ce document décrit les directives et les normes de documentation pour le kit de ressources Mixed Reality (MRTK). Cela fournit une introduction aux aspects techniques de l’écriture et de la génération de documentation, pour mettre en évidence les pièges courants et 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
    2. Le nombre réel dans le code n’est pas pertinent ; L’analyse prend soin de définir le numéro d’élément correct.
  • Listes de points à puces
    • Listes à puces imbriquées
  • Texte en gras avec **double astérisque**
  • texteitalique avec _soulignement_ ou *astérisque unique*
  • Texte highlighted as code dans une phrase « utilisation de backquotes »
  • Liens vers les pages de documentation recommandations en matière de documentation MRTK
  • Liens vers des ancres dans une page ; les ancres sont formées en remplaçant les espaces par des tirets et en convertissant en minuscules

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

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

Lors de la mention du code dans une phrase use a single backtick.

Todos

Évitez d’utiliser des TODOs dans des documents, car au fil du temps ces TODOs (comme le code TODOs) ont tendance à accumuler et à obtenir des informations sur la façon dont elles doivent être mises à jour et pourquoi elles sont perdues.

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

  1. Créez un nouveau problème sur Github 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 le todo dans la documentation.

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Un bref flou sur le problème -->

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 les cas pertinents spéciaux.

Notes

Exemple d’une note

Avertissement

Exemple d’avertissement

Important

Exemple de commentaire important

Mise en page

Introduction

La partie juste après le titre du chapitre principal doit servir d’introduction courte à ce que le chapitre est à propos. Ne faites pas cela trop long, ajoutez plutôt des sous-titres. Celles-ci permettent de lier des sections et peuvent être enregistrées en tant que signets.

Corps principal

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

Mini Sections

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

Section « Voir aussi »

La plupart des pages doivent se terminer par un chapitre appelé Voir également. Ce chapitre est simplement une liste à puces de liens vers des pages liées à cette rubrique. 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 principale, 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 (TOC)

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 du 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 du pouce : Essayez de sonner un professionnel. Cela signifie généralement d’éviter un « ton conversationnel ». Essayez également d’éviter l’hyperbole et le sensationnelisme.

  1. N’essayez pas d’être (trop) drôle.
  2. N’écrivez jamais 'I'
  3. Évitez « nous ». Cela peut généralement être répliqué 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 modification simple, votre nuanceur devient configurable ! »> : « Les nuanceurs peuvent être configurables avec peu d’effort. »
  5. N’utilisez pas les expressions « sloppy ».
  6. Évitez d’être trop excités, 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 le cas de phrase pour les titres. Ie. mettre en majuscules la première lettre et les noms, mais rien d’autre.
  • Utilisez l’anglais normal pour tout le reste. Cela signifie ne pas mettre en majuscules les mots arbitraires, même s’ils contiennent une signification spéciale 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 (qui est la méthode préférée), le nom de chapitre standard utilise toujours des lettres majuscules, ce qui interrompt la règle d’aucune mise en majuscules arbitraire à l’intérieur du texte. Par conséquent, utilisez un nom de lien personnalisé pour corriger la mise en majuscules. Par exemple, voici un lien vers la documentation du contrôle des limites .
  • Utilisez des noms en majuscules, tels que Unity.
  • Ne capitalisez pas « éditeur » lors de l’écriture de l’éditeur Unity.

Accentuation et mise en surbrillance

Il existe deux façons de souligner ou de mettre en surbrillance les mots, de les mettre en gras ou de les rendre italiques. L’effet du texte en gras est que le texte en gras s’affiche et peut donc être facilement remarqué lors de l’écréation d’un morceau de texte ou même de faire défiler sur une page. Gras est excellent pour mettre en évidence les expressions que les gens doivent mémoriser. Toutefois, utilisez rarement du texte en gras, car il est généralement distrait.

Souvent, on veut « regrouper » quelque chose qui appartient logiquement ensemble ou mettre en surbrillance un terme spécifique, car il a une signification spéciale. Ces choses n’ont pas besoin de se distinguer 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 rendre italique pour le regrouper logiquement, sans être distraire.

En général, essayez d’éviter les surbrillances de texte inutiles. Les termes spéciaux peuvent être mis en surbrillance une fois pour rendre le lecteur conscient, ne répétez pas de telles mises en surbrillance tout au long du texte, lorsqu’il ne sert plus d’objet et ne distraire que.

Mention des entrées de menu

Lorsque vous mentionnez une entrée de menu que l’utilisateur doit cliquer, la convention actuelle est la suivante : 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 pense à quel point il serait ennuyeux, si la même page s’ouvre 20 fois.

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

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

Lors de l’ajout d’un lien, déterminez s’il doit également être répertorié dans la section Voir aussi . De même, vérifiez si un lien vers la nouvelle page doit être ajouté à la page liée.

Images / captures d’écran

Utilisez des captures d’écran avec parcimonie. La gestion des images dans la documentation est beaucoup de travail, de petites modifications de l’interface utilisateur peuvent apporter beaucoup de captures d’écran obsolètes. 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 le 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 d’éléments dans une capture d’écran qui ne sont pas pertinentes pour ce qui est affiché. Par exemple, lorsqu’un effet de rendu est affiché, effectuez une capture d’écran de la fenêtre d’affichage, mais excluez toute interface utilisateur autour de celle-ci. Montrant une interface utilisateur, essayez de déplacer des fenêtres de telle sorte que seule la 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 affiche les boutons de barre d’outils importants, mais excluez tout autour de lui.
  4. Utilisez uniquement des images faciles à reproduire. Cela signifie qu’il n’y a pas de marqueurs de peinture ni de surbrillance dans des captures d’écran. Tout d’abord, il n’existe pas de règles cohérentes quant à l’apparence de ces règles. 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 d’efforts pour recréer un GIF animé. Attendez-vous à être responsable de la recréer jusqu’à la fin du temps, ou attendez-vous à ce que les gens le jettent, s’ils ne veulent pas passer ce temps.
  6. Conservez le nombre d’images dans un article faible. Souvent, une bonne méthode consiste à créer une capture d’écran globale de certains outils, qui montre tout, puis à décrire le reste dans le texte. Cela facilite le remplacement de la capture d’écran si nécessaire.

Voici d’autres aspects :

  • 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 conserver les choses aussi cohérentes que possible.
  • La largeur de l’image par défaut est de 500 pixels, car cela s’affiche bien sur la plupart des moniteurs. Essayez de ne pas s’en écarter trop. La largeur de 800 pixels doit être la valeur maximale.
  • Utilisez des PNG pour les captures d’écran de l’interface utilisateur.
  • Utilisez des PNG ou des JPG pour les captures d’écran de la fenêtre d’affichage 3D. Préférer la qualité au rapport de compression.

Liste des propriétés du composant

Lorsque vous documentez une liste de propriétés, utilisez le texte en gras pour mettre en surbrillance le nom de la propriété, puis les sauts de ligne et le 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 de page

  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 connaisse la rubrique pour vérifier l’exactitude technique de la rubrique.
  4. Demander à quelqu’un de lire la page pour le style et la mise en forme. Il peut s’agir d’une personne inconnue de la rubrique, 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 cette opération, 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 de synthèse de classe, de struct, d’énumération

Si une classe, un struct ou une énumération est ajouté à MRTK, son objectif doit être décrit. Il s’agit de prendre la forme 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 notes, immédiatement sous le 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.

Propriétés, méthode, blocs de synthèse d’événements

Les propriétés, méthodes et é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, Éveil, Démarrage, Mise à jour).

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 le cadre de 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 des 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, les scripts doivent inclure au moins le contenu de l’info-bulle dans un bloc de synthèse.

/// <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 pour 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 du kit de ressources Mixed Reality 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é fourni.

Lorsqu’une fonctionnalité est ajoutée (ou que l’utilisation est modifiée), la 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 à se familiariser avec une fonctionnalité ou un concept.

Documentation de conception

Mixed Reality permet 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 aussi fluide que 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 dans lesquels la documentation de conception peut être utile :

  • Modèles de curseur
  • Visualisations de mappage spatial
  • Fichiers d’effet sonore

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

Cela peut ou ne pas être différent de la recommandation de conception sur le site MS Developer

Notes de performances

Certaines fonctionnalités importantes sont à un coût de performances. Souvent, ce code dépend très 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 de l’API et de la vue d’ensemble.

Changements cassants

La documentation sur les changements cassants consiste à se composer d’un fichier de niveau supérieur qui lie les breaking-changes.md individuels de chaque zone de fonctionnalité.

La zone de fonctionnalité breaking-changes.md fichiers doit contenir la liste de toutes les modifications cassants connues pour une version donnée , ainsi que l’historique des changements cassants des 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 le niveau de fonctionnalité breaking-changes.md fichiers seront 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 pour la 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 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 empaquetés dans le Pack de création docs publié par Microsoft.

Voir aussi