Conseils d’écriture pour les guides d’installation
Si vous ne pouvez pas consulter un guide de style complet, suivez ces conseils pour améliorer considérablement votre contenu.
Utiliser la voix active
Évitez la voix passive (verbe être + verbe au passé). Pour rendre votre texte plus dynamique, clair et (souvent) plus court, essayez d’utiliser des acteurs et la voix active autant que possible.
| Preferred | Discouraged | Une fois que vous avez ajouté la configuration requise, Auth0 traitera toutes les connexions pour votre locataire en utilisant cette règle. Avant d’activer l’intégration en production, assurez-vous d’avoir configuré correctement tous les composants et vérifié sur un locataire de test. | Une fois la configuration requise ajoutée, toutes les connexions de votre locataire seront traitées par cette règle. Veuillez vous assurer que tous les composants ont été configurés correctement et vérifiés sur un locataire de test avant d’activer l’intégration dans la production. |
Rendre les titres des liens faciles à numériser
Lorsque vous créez des liens vers d’autres ressources, assurez-vous que le lien décrit l’action ou la tâche dans le document vers lequel le lien pointe. Le texte de lien générique réduit la facilité de numérisation en obligeant les lecteurs à lire tout le texte entourant un lien pour identifier ce qu’ils doivent sélectionner.
| Preferred | Discouraged | |-----------|-------------| | Vous pouvez utiliser Auth0 Dashboard ou Management API pour [personnaliser le texte pour la nouvelle expérience de connexion universelle] (/docs/customize/universal-login-pages/universal-login-page-templates). | Cliquez [ici] (/docs/get-started). | | Pour apprendre comment attribuer des rôles aux membres d’organisations, lisez [Ajouter des rôles aux membres d’organisation] (/docs/manage-users/organizations/configure-organizations/add-member-roles). | Vous pouvez consulter ce lien. |
Écrire des instructions adaptées à tous les appareils
N’oubliez pas que les interfaces utilisateur s’affichent différemment sur différents appareils. De plus, gardez à l’esprit que les utilisateurs peuvent utiliser des appareils adaptatifs pour consulter votre contenu.
| Preferred | Discouraged | |-----------|-------------| | Sélectionnez Create (Créer). |Cliquez sur Create (Créer). | | Passez à la vue Applications. | Passez à l’onglet Applications. | | Localisez le Client Secret (Secret client). | Faites défiler l’écran vers le haut jusqu’au Client Secret (Secret client). |
Utiliser correctement les verbes et noms/adjectifs
Faites attention aux mots qui peuvent être utilisés à la fois comme verbes et comme noms ou adjectifs. Les formes verbales nécessitent généralement un espace entre les mots, tandis que les noms et les adjectifs peuvent être composés.
| Preferred | Discouraged | |-----------|-------------| | Connectez-vous à votre compte. | Connectez-vous à votre compte. | | Auth0 traite les connexions. | Auth0 traite les connexions. | | Configurez votre matériel. | Configurez votre matériel. | | Décrivez votre configuration matérielle. | Décrivez votre configuration matérielle. |
Utiliser les lettres minuscules pour les entêtes
Mettez en majuscule uniquement la première lettre et tous les noms propres ou noms de produits Auth0.
| Préféré | Déconseillé |
|---|---|
| Ajouter une dépendance | Ajouter une Dépendance |
| Valider une reprise de connexion | Valider une Reprise de Connexion |
| Créer une Action | Créer une action |
Utiliser l’indicatif présent pour les entêtes
Évitez toute redondance inutile en utilisant des temps verbaux simples pour les entêtes.
| Preferred | Discouraged |
|---|---|
| Affecter et modifier des utilisateurs | Affectaction et modification des utilisateurs |
| Connecter une base de données personnalisée | Comment connecter une base de données personnalisée |
Rédiger les étapes de manière concise
Lorsque vous rédigez le texte d’introduction des étapes, soyez direct et concis. Gardez à l’esprit que les utilisateurs savent déjà ce qu’ils doivent faire avec une liste numérotée d’étapes.
| Preferred | Discouraged | |-----------|-------------| | Pour installer la trousse SDK : | Suivez les étapes ci-dessous : |
Définir les attentes des utilisateurs dans les étapes
Informez les utilisateurs de ce que devrait être le résultat de leur comportement avant de décrire le comportement à adopter.
| Preferred | Discouraged |
|---|---|
| Pour activer cette intégration, sélectionnez Enregistrer les modifications. | Sélectionnez Enregistrer les modifications pour activer cette intégration. |
Énumérer les actions dans les étapes dans l’ordre
À chaque étape, indiquez à l’utilisateur ce qu’il doit faire dans l’ordre où il doit le faire.
| Préféré | Déconseillé |
|---|---|
| Repérez la section Integrations , et sélectionnez Ajouter une intégration. | Sélectionnez Ajouter une intégration sous la section Integrations. |
Utiliser les notes et avertissements de manière adéquate
Les notes et les avertissements ont des fonctions différentes. Les notes doivent inclure des informations générales qu’il serait utile de connaître, tandis que les avertissements contiennent des informations pouvant entraîner un échec si elles ne sont pas suivies.
S’il vaut la peine que des informations soient présentées comme un avertissement, vous devriez le placer précisément là où l’utilisateur doit effectuer l’action correspondante. Les utilisateurs ne devraient pas avoir à chercher les avertissements.