Skip to main content
Contributor's Guide
La version française est une traduction automatique. La version anglaise prévaut sur la française en cas de divergence.

Guide de style des documents NetApp

Contributeurs
PDF

Notre style est conversationnel et empathique, mais nous restons professionnels et faisons le point. Suivez ces instructions lorsque vous écrivez du contenu pour les documents NetApp.

Écrire de manière conversaïe

Écrivez comme vous parlez lorsque vous expliquez quelque chose à un collègue professionnel. Afin d'établir un lien entre vous et votre public.

Trop formel Trop décontracté Notre style

En cas de problèmes avec le Tiering BlueXP, vous pouvez afficher l'état de santé dans le tableau de bord de cluster pour déterminer la raison pour laquelle l'erreur s'est produite. L'état de santé reflète l'état du système ONTAP et du connecteur de service.

Ce n'est pas amusant quand les pannes se produisent. Pour plus d'informations, consultez le tableau de bord du cluster et découvrez ce qui s'est passé et ce qui est affecté.

En cas de défaillance, le Tiering BlueXP affiche un état d'intégrité « échec » dans le tableau de bord du cluster. Afficher l'état pour obtenir des informations sur la défaillance.

Avant de pouvoir provisionner le stockage, vous devez détecter votre cluster ONTAP à partir de BlueXP. Une fois la détection terminée, vous devez ouvrir l'environnement de travail pour provisionner le stockage.

Il vous suffit de détecter votre cluster ONTAP à partir de BlueXP, puis d'ouvrir l'environnement de travail pour commencer à provisionner le stockage. Facile !

Après avoir découvert votre cluster ONTAP à partir de BlueXP, ouvrez l'environnement de travail pour provisionner le stockage.

Au démarrage de l'assistant d'installation, suivez les instructions de l'assistant pour configurer le nœud et le joindre au cluster. Les étapes suivantes vous permettent de suivre les étapes de l'assistant.

L'assistant d'installation apparaît (comme pour la magie), pour vous guider dans le processus simple de configuration du nœud et de connexion au cluster.

Suivez les instructions de l'assistant d'installation pour configurer le nœud et le joindre au cluster.

Vous pouvez choisir parmi plusieurs types de formats de contenu pour installer et configurer votre nouveau système. Chaque type de format fournit des instructions complètes. Choisissez le type de format qui correspond le mieux à votre mode d'apprentissage.

Comment souhaitez-vous installer et installer votre système ? Nous vous fournissons des instructions dans plusieurs formats de contenu, mais vous ne savez que ce que vous aimez apprendre.

Choisissez un type de format de contenu pour vous guider lors de l'installation et de la configuration de votre système.

Utiliser les contractions

Les contractions renforcent un ton conversationnel, et beaucoup de contractions sont faciles à comprendre et à traduire.

Développez pour en savoir plus

  • Utilisez des contractions comme celles-ci, qui sont faciles à comprendre et à traduire :

    ne le sont pas

    c'est possible

    n'est pas

    c'est le cas

    ce n'était pas le cas

    c'est

    je n'ai pas été

    allons-y

    pas

    nous le ferons (si une tension future est nécessaire)

    pas

    pas (si une tension future est nécessaire)

    ne le faites pas

    vous (si une tension future est nécessaire)

  • N'utilisez pas les contractions comme celles-ci, qui sont difficiles à comprendre et à traduire :

    nous l'aurions fait

    devrait l'avoir

    je ne l'aurais pas fait

    ne devrait pas avoir

    pourrait-il avoir

    je n'en aurais pas pu

Écrivez simplement

Évitez les mots grands et confus. Privilégier la simplicité. Vous expliquez quelque chose à un collègue professionnel, sans montrer votre vocabulaire.

Au lieu de cela: "Dissociez l'utilisateur de votre compte NetApp Cloud Central."

Procédez comme suit : « Supprimer l'utilisateur de votre compte NetApp Cloud Central ».

Écriture minimale

Des phrases courtes et simples facilitent la lecture ou la numérisation du contenu. Il est possible d'utiliser une phrase plus longue tous les jours, mais de la suivre avec une phrase plus courte. Comme ceci.

Au lieu de cela : « pour répliquer des données entre un système Cloud Volumes ONTAP dans AWS et les systèmes ONTAP d'autres réseaux, vous devez disposer d'une connexion VPN entre le VPC Amazon et l'autre réseau, par exemple un réseau Azure vnet ou votre réseau d'entreprise. »

Faites ceci: "La réplication de données entre les réseaux nécessite une connexion via un VPN. Par exemple, entre votre VPC Amazon et votre réseau d'entreprise ou entre AWS et Azure. »

Posez-vous les questions suivantes :

  • Les utilisateurs ont-ils besoin de ce contenu à cet endroit, à ce stade ?

  • L'interface utilisateur guide-t-elle déjà suffisamment l'utilisateur ? Si ce n'est pas le cas, quels conseils supplémentaires peuvent être ajoutés brièvement ?

  • Puis-je présenter le contenu en moins de mots sans paraître trop formel ou trop décontracté?

  • Puis-je raccourcir ou simplifier une longue phrase ou la diviser en deux ou plusieurs phrases?

  • Puis-je utiliser une liste pour rendre le contenu plus scannable ?

  • Puis-je utiliser un graphique pour augmenter ou remplacer un bloc de texte ?

Écrivez activement

Éviter la voix passive est une règle standard pour la rédaction technologique, mais il est particulièrement important d'utiliser la voix active lorsque vous voulez faire entendre la conversation.

Voix active

Utilisez la voix active pour que le sujet de la phrase exécute l'action du verbe. Cela signifie généralement que le verbe suit le sujet de la phrase. La voix active permet d'écrire de manière nette et claire. Utilisez la voix active et les utilisateurs d'adresse directement comme « vous », sauf si vous avez une raison spécifique d'utiliser la voix passive.

Voici quelques exemples de bonne écriture vocale active. Écrivez comme ceci :

  • Indiquez les autorisations requises avant de déployer votre premier cluster.

  • Si vous arrêtez le système de façon incorrecte, l'interface affiche un message d'avertissement.

  • NetApp a reçu le contrat.

Voix passive

Dans la voix passive, le doteur de l'action n'est pas clair :

  • Un message d'avertissement s'affiche si le système n'est pas correctement arrêté.

  • NetApp a obtenu le contrat.

Utilisez la voix passive lorsque :

  • Vous ne savez pas qui ou ce qui a effectué l'action.

  • Vous voulez éviter de blâmer les utilisateurs pour les résultats d'une action.

  • Vous ne pouvez pas écrire autour de lui, par exemple pour certaines informations préalables.

Humeur impérative

Utilisez l'humeur impérative pour les étapes, directives, demandes et en-têtes des listes d'actions utilisateur :

  • « Sur la page environnements de travail, cliquez sur découvrir et sélectionnez ONTAP Cluster. »

  • « Faites pivoter la poignée de came de manière à ce qu'elle affleure l'alimentation électrique. »

Envisagez d'utiliser la voix impérative pour remplacer la voix passive :

Au lieu de cela: "Les autorisations requises doivent être fournies avant de déployer votre premier cluster."

Faites ceci: "Fournissez les autorisations requises avant de déployer votre premier cluster."

Évitez d'utiliser la voix impérative pour intégrer les étapes dans les informations conceptuelles et de référence.

Pour plus d'informations sur les conventions verb, voir :

Écrire un contenu cohérent

« Ecrivez comme vous parlez lorsque vous expliquez quelque chose à un collègue professionnel » signifie quelque chose de différent pour tout le monde. Notre style professionnel et informel nous permet de nous connecter aux utilisateurs et augmente la fréquence des incohérences mineures entre plusieurs auteurs contributeurs :

  • Concentrez-vous sur la clarté et la facilité d'utilisation du contenu. Si tout le contenu est clair et facile à utiliser, les incohérences mineures n'ont pas d'importance.

  • Soyez cohérent dans la page que vous écrivez.

  • Suivez toujours les instructions de la section Écrivez pour un public international.

Utiliser un langage inclusif

NetApp estime que sa documentation produit ne doit pas contenir de discrimination et d'exclusivité. Les mots que nous utilisons peuvent faire la différence entre établir une relation positive avec nos clients ou les aliéner. En particulier avec les mots écrits, l'impact est plus important que l'intention.

Lorsque vous créez du contenu pour les produits NetApp, évitez tout langage pouvant être interprété comme dégradant, raciste, sexiste ou oppressif. Utilisez plutôt une langue accessible et accueillante pour tous ceux qui ont besoin d'utiliser la documentation. Par exemple, au lieu de « maître/esclave », utilisez « principal/secondaire ».

Utilisez la première langue dans laquelle nous nous référons d'abord à la personne, suivie de la déficience.

Ne l'utilisez pas, lui, son, elle, elle, ou hers dans les références génériques. Au lieu de cela :

  • Réécrivez la phrase pour utiliser la deuxième personne (vous).

  • Réécrivez la phrase pour avoir un nom et un pronom pluriels.

  • Utilisez "le" ou "a" au lieu d'un pronom (par exemple, "le document").

  • Désigne le rôle d'une personne (par exemple, lecteur, employé, client ou client).

  • Utilisez le terme « personne » ou « personne ».

Exemples de mots et de phrases considérés comme inclusifs ou exclusifs

Exemples inclusifs Exemples exclusifs

Primaire/secondaire

Maître/esclave

Liste autorisée

Liste blanche

Liste bloquée

Liste noire

Arrêter

Tuer

Ne répondez plus

Attendez

Fin ou Annuler

Abandonner

Heure-personne

Heure de main-d'œuvre

Les développeurs ont besoin d'accéder aux serveurs dans leurs environnements de développement, mais ils n'ont pas besoin d'accéder aux serveurs dans Azure.

Un développeur a besoin d'accéder aux serveurs dans son environnement de développement, mais il n'a pas besoin d'accéder aux serveurs dans Azure.

Personne aveugle

Malvoyant

Personne ayant une faible vision

Malvoyantes

Arriver au point

Chaque page doit commencer par ce qui est le plus important pour l'utilisateur. Nous devons savoir ce que l'utilisateur essaie de faire et nous concentrer sur son aide à atteindre cet objectif. Nous devrions également ajouter des mots clés au début de la phrase pour améliorer la capacité de numérisation.

Suivez les directives générales suivantes :

  • Soyez précis.

  • Évitez les mots de remplissage.

  • Être courts.

  • Utilisez du texte formaté ou des listes à puces pour mettre en surbrillance les points clés.

Exemples d'accès au point

Bons exemples Mauvais exemples

Si votre entreprise applique des règles de sécurité strictes, utilisez le chiffrement des données à la volée pour synchroniser les données entre les serveurs NFS de différents réseaux.

Cloud Sync peut synchroniser les données d'un serveur NFS vers un autre serveur NFS à l'aide du chiffrement des données à la volée. Le cryptage des données peut vous aider si vous disposez de politiques de sécurité strictes pour le transfert de données sur des réseaux.

Gagnez du temps en créant un modèle de document qui inclut les styles, les formats et les mises en page que vous utilisez le plus souvent. Utilisez ensuite le modèle chaque fois que vous créez un nouveau document.

Les modèles fournissent un point de départ pour la création de nouveaux documents. Un modèle peut inclure les styles, les formats et les mises en page que vous utilisez fréquemment. Envisagez de créer un modèle si vous utilisez souvent la même mise en page et le même style pour les documents.

ASTRA Control propose trois modes opérationnels que vous pouvez attribuer à vos utilisateurs pour contrôler soigneusement l'accès entre Astra Control et votre environnement cloud.

ASTRA Control vous permet d'attribuer l'un des trois modes opérationnels aux utilisateurs de vos comptes AWS. Ces modes vous permettent de contrôler soigneusement l'accès entre Astra Control et votre environnement cloud en fonction de vos règles IT.

Utilisez beaucoup de visuels

La plupart des gens sont des apprenants visuels. Utilisez des vidéos, des diagrammes et des captures d'écran pour améliorer l'apprentissage, diviser des blocs de texte et fournir aux utilisateurs un indice visuel de leur emplacement dans les instructions de tâche.

  • Incluez une phrase d'entrée qui décrit l'image suivante : « l'illustration suivante montre les voyants du bloc d'alimentation CA sur le panneau arrière. »

  • Se reporter à l'emplacement de l'illustration comme suit ou précédent, et non au-dessus ou au-dessous.

  • Utilisez le texte alt sur les éléments visuels intégrés.

  • Si le visuel concerne une étape, incluez le visuel juste après l'étape et en retrait pour l'aligner avec le numéro de l'étape.

Meilleures pratiques sur les captures d'écran :

  • Ne pas inclure plus de 5 captures d'écran par tâche.

  • N'incluez pas de texte dans une capture d'écran. Utilisez plutôt des symboles numérotés.

  • Soyez judicieux avec les captures d'écran que vous choisissez d'inclure. Les captures d'écran peuvent rapidement être obsolètes.

Meilleures pratiques sur les vidéos ou les animations :

  • Les vidéos doivent durer moins de 5 minutes.

Exemples

Créer un contenu scannable

Aidez les lecteurs à trouver du contenu rapidement en organisant le texte sous les en-têtes de section et en utilisant des listes et des tableaux. Les titres, phrases et paragraphes doivent être courts et faciles à lire. Les informations les plus importantes doivent être fournies en premier.

Exemples

Créez des flux de travail qui aident les utilisateurs à atteindre leurs objectifs

Les utilisateurs lisent notre contenu pour atteindre un objectif spécifique. Les utilisateurs veulent trouver le contenu dont ils ont besoin, atteindre leurs objectifs et rentrer chez eux. Notre travail n'est pas de documenter des produits ou des fonctionnalités. Notre travail consiste à documenter les objectifs des utilisateurs. Les flux de travail constituent le moyen le plus direct d'aider les utilisateurs à atteindre leurs objectifs.

Un flux de travail est une série d'étapes ou de sous-tâches décrivant comment atteindre un objectif utilisateur. L'étendue d'un workflow est un objectif complet.

Par exemple, les étapes de création d'un volume ne seraient pas un flux de travail, car la création d'un volume en lui-même n'est pas un objectif complet. Les étapes permettant de mettre le stockage à disposition d'un serveur ESX peuvent être un flux de travail. Les étapes comprennent non seulement la création d'un volume, mais l'exportation du volume, la définition des autorisations nécessaires, la création d'une interface réseau, etc.

Les flux de travail sont dérivés des cas d'utilisation des clients. Un flux de travail ne montre que la meilleure façon d'atteindre l'objectif.

Organisez le contenu en fonction de l'objectif de l'utilisateur

Aidez les utilisateurs à trouver des informations rapidement en organisant le contenu en fonction de l'objectif que l'utilisateur tente d'atteindre. Cette norme s'applique à la table des matières (navigation) d'un site de documentation, ainsi qu'aux pages individuelles qui apparaissent sur le site.

Organisez le contenu comme suit :

La première entrée de la navigation de gauche (niveau élevé)

Organisez le contenu autour des objectifs que l'utilisateur tente d'atteindre. Par exemple, la première entrée dans la navigation pour le site peut être « commencer » ou « protéger les données ».

Les entrées de second niveau dans la navigation pour le site de documentation (niveau moyen)

Organiser le contenu autour des grandes tâches qui composent les objectifs.

Par exemple, la section « mise en route » peut inclure les pages suivantes :

  • Avant l'installation

  • Installer et configurer <product name>

  • Configuration des licences

  • Que pouvez-vous faire ensuite

Pages individuelles (niveau détaillé)

Sur chaque page, organisez le contenu autour des tâches individuelles qui composent les grandes tâches. Par exemple, le contenu dont les utilisateurs ont besoin pour préparer l'installation ou pour configurer la reprise sur incident.

Une page peut décrire une ou plusieurs tâches. S'il existe plusieurs tâches, elles doivent être décrites dans des sections distinctes de la page. Chaque section doit se concentrer sur un seul aspect de l'apprentissage ou de la réalisation de la tâche générale. Il peut s'agir d'informations conceptuelles et de référence requises pour effectuer la tâche.

Écrivez pour un public international

Notre documentation est lue par de nombreux utilisateurs dont la langue principale n'est pas l'anglais. Nous traduisons notre contenu dans d'autres langues à l'aide d'outils de traduction automatique neural ou de traduction humaine. Pour soutenir notre public international, nous rédigeons des contenus faciles à lire et à traduire.

Suivez ces instructions pour écrire à l'attention d'un public international :

  • Écrivez des phrases courtes et simples.

  • Utiliser la grammaire et la ponctuation standard.

  • Utilisez un mot pour un sens et un sens pour un mot.

  • Utiliser des contractions courantes.

  • Utilisez les graphiques pour clarifier ou remplacer du texte.

  • Évitez d'incorporer du texte dans les graphiques.

  • Évitez d'avoir trois noms ou plus dans une chaîne.

  • Éviter les antécédents peu clairs.

  • Évitez le jargon, les colloquialismes et les métaphores.

  • Évitez les exemples non techniques.

  • Éviter d'utiliser des retours durs et un espacement.

  • N'utilisez pas l'humour ou l'ironie.

  • N'utilisez pas de contenu discriminatoire.

  • N'utilisez pas de langage biaisé à l'égard du sexe, sauf si vous écrivez pour un personnage spécifique.

Lignes directrices a à Z.

acronymes et abréviations

Utilisez des acronymes et des abréviations bien connus pour vous familiariser, mais évitez les acronymes obscurs qui pourraient nuire à la clarté et à la findabilité. Pour des conventions supplémentaires concernant les acronymes et les abréviations, reportez-vous à la "Guide des styles d'écriture Microsoft".

voix active (par rapport à la voix passive)

Reportez-vous à la section Écrivez activement.

définitions

Les avertissements sont un outil puissant lorsqu'ils sont utilisés correctement. Ils peuvent attirer l'attention sur des informations importantes, fournir des conseils utiles ou avertir les utilisateurs des dangers potentiels. Lorsqu'ils sont utilisés de manière excessive, ils perdent leur impact et peuvent entraîner une fatigue de l'utilisateur. Voici quelques lignes directrices pour assurer l'utilisation efficace des admonitions.

Utilisez les étiquettes suivantes pour séparer les admonitions du flux de contenu principal :

  • REMARQUE utilisez la NOTE pour mettre en évidence les informations importantes qui doivent se démarquer du reste du texte. Cependant, évitez d'utiliser la NOTE pour des informations « agréables à connaître » qui ne sont pas essentielles pour que les utilisateurs comprennent ou remplissent une tâche. Le but d'une NOTE est d'attirer l'attention du lecteur sur les points critiques qu'ils pourraient autrement négliger.

  • Les conseils doivent être utilisés avec parcimonie, voire avec parcimonie, car notre politique est de documenter les informations sur les meilleures pratiques par défaut. Si nécessaire, utilisez LE CONSEIL pour mettre en évidence les informations sur les meilleures pratiques qui aident les utilisateurs à utiliser un produit ou à effectuer une étape ou une tâche plus facilement et plus efficacement. Un CONSEIL doit fournir des conseils ou des raccourcis utiles qui peuvent améliorer l'expérience de l'utilisateur.

  • ATTENTION faites ATTENTION pour avertir les utilisateurs des conditions ou des actions susceptibles d'entraîner des conséquences indésirables, notamment des blessures ou des dommages matériels. FAITES attention aux dangers potentiels que l'utilisateur doit éviter pour éviter les blessures ou les perturbations.

  • MEILLEURES PRATIQUES utilisez LES MEILLEURES PRATIQUES pour mettre en évidence les moyens optimaux de réaliser des tâches ou d'utiliser un produit. Ce ne sont pas de simples suggestions, mais des stratégies qui ont été validées par des experts ou des normes de l'industrie.

    • Qu'est-ce qui fait une MEILLEURE PRATIQUE? Il s'agit d'une stratégie exploitable et spécifique à une tâche qui offre des avantages clairs et est soutenue par des sources fiables.

    • Quand puis-je les utiliser? Vous pouvez utiliser les MEILLEURES PRATIQUES pour tous les types de contenu et pour tous les publics. Comme les CONSEILS, utilisez-les avec parcimonie pour maintenir leur signification.

    • Comment les formater? Présentez LES MEILLEURES PRATIQUES dans un format cohérent et convivial. Il peut s'agir d'une liste à puces, d'une liste numérotée ou d'un paragraphe, selon le contexte.

Directives supplémentaires

  • Utilisez uniquement les avertissements pris en charge. Tout autre type de formatage n'est pas pris en charge.

  • Évitez de trop utiliser les avertissements. Une utilisation excessive peut conduire les utilisateurs à ignorer ces sections importantes, car ils les voient comme le « tiroir de courrier indésirable » de nos documents.

  • En règle générale, limitez le nombre d'admonitions à un maximum de 3 par page.

  • Fournir des informations claires et concises dans l'admontion. Le message doit être bref et précis, permettant aux utilisateurs de comprendre rapidement l'importance des informations fournies.

  • Évitez les admonitions AsciiDoc dans une table. Si le contenu doit être identifié comme une note, un conseil ou une mise en garde, utilisez Remarque :, Conseil :, ou attention : en tant qu'entrée en ligne du texte.

après (au lieu d'une seule fois)

  • Utilisez « après » pour indiquer une chronologie : « allumez votre ordinateur après l'avoir branché ».

  • N'utilisez qu'une seule fois pour dire « une fois ».

également

  • Utilisez « également » pour dire « plus ».

  • N'utilisez pas « également » pour désigner « alternativement ».

et/ou

Choisissez le terme le plus précis s'il y en a un. Si aucun des deux termes n'est plus précis que l'autre, utilisez « et/ou ».

comme

N'utilisez pas « comme » pour dire « parce ».

en utilisant (plutôt que « utiliser » ou « avec »)

  • Utilisez « en utilisant » lorsque l'entité qui utilise est l'objet : « vous pouvez ajouter de nouveaux composants au référentiel à l'aide du menu composants. »

  • Vous pouvez commencer une phrase par « en utilisant » ou « avec », qui sont parfois acceptables avec les noms de produits : « avec SnapDrive, vous pouvez gérer des disques virtuels et des copies Snapshot dans un environnement Windows. »

peut (par opposition à « peut », « peut », « devrait » ou « doit »)

  • Utilisez « CAN » pour indiquer la capacité : « vous pouvez valider vos modifications à tout moment au cours de cette procédure. »

  • Utilisez « peut » pour indiquer la possibilité : « le téléchargement de plusieurs programmes peut affecter le temps de traitement. »

  • N'utilisez pas « May », ce qui est ambigu car cela peut signifier soit la capacité, soit la permission.

  • Utilisez « devrait » pour indiquer une action recommandée mais facultative. Envisagez plutôt d'utiliser une autre expression, telle que « nous recommandons ».

  • Évitez d'utiliser « must » car c'est le cas passif. Envisagez de restaper la pensée comme une instruction à l'aide de la voix impérative. Si vous utilisez « doit », utilisez-le pour indiquer une action ou une condition requise.

capitalisation

Utilisez la casse de style phrase (minuscule) pour presque tout. Seule la majuscule :

  • Le premier mot des phrases et en-têtes, y compris les en-têtes des tableaux

  • Le premier mot des éléments de la liste, y compris des fragments de phrase

  • Noms corrects

  • Titres et sous-titres du DOC (capitalisez tous les mots principaux et prépositions de cinq lettres ou plus)

  • Les éléments de l'interface utilisateur, mais uniquement s'ils sont capitalisés dans l'interface. Sinon, utilisez la minuscule.

mises en garde

Reportez-vous à la section définitions.

contractions

Utiliser contractions dans le cadre de l'écriture conversationnellement.

s'assurer (plutôt que « confirmer » ou « vérifier »)

  • Utilisez « Assurez-vous » pour dire « pour vous assurer ». Indiquez « que », selon le cas : « Assurez-vous qu'il y a suffisamment d'espace blanc autour des illustrations. »

  • N'ayez jamais recours à la « garantie » pour promettre ou garantir : « utilisez Cloud Manager pour vous assurer de provisionner les volumes NFS et CIFS sur les clusters ONTAP. »

  • Utilisez « confirmer » ou « vérifier » si vous voulez dire que l'utilisateur doit vérifier un élément qui existe déjà ou qui s'est déjà produit : « vérifier que NFS est configuré sur le cluster ».

graphiques

Reportez-vous à la section Utilisez beaucoup de visuels.

grammaire

Sauf mention contraire, suivez les conventions de grammaire, de ponctuation et d'orthographe détaillées dans :

sinon

Ne pas utiliser « si non » seul pour se référer à la phrase précédente :

  • Au lieu de cela: "L'ordinateur doit être éteint. Si ce n'est pas le cas, éteignez-le. »

  • Faire ceci: "Vérifier que l'ordinateur est éteint."

si (par opposition à « si » ou « quand »)

  • Utilisez « if » pour indiquer une condition, par exemple dans les constructions « if this, then that ».

  • Indiquez s'il y a une condition « ou non » énoncée ou implicite. Pour faciliter la traduction, il est souvent préférable de remplacer "si" ou non par "si" seul.

  • Utilisez « quand » pour indiquer un passage de temps.

voix impérative

Reportez-vous à la section Écrivez activement.

fonctionnalités ou versions futures

Ne pas se référer au calendrier ou au contenu des prochaines versions ou fonctionnalités de produits, autre que de dire qu'une fonctionnalité ou une fonction est « actuellement non prise en charge ».

Articles de la base de connaissances : référence à

Consultez les articles de la base de connaissances NetApp le cas échéant. Pour les pages de ressources et le contenu GitHub, placez le lien en cours d'exécution.

listes

Les listes d'informations sont généralement plus faciles à numériser et à absorber que les blocs de texte. Envisagez des façons de simplifier les informations complexes en les présentant sous forme de liste. Voici quelques directives générales, mais utilisez votre jugement :

  • Assurez-vous que la raison de la liste est claire. Présentez la liste avec une phrase complète, un fragment de phrase avec deux-points ou un en-tête.

  • Lorsque vous utilisez une liste dans une liste, limitez la structure à deux niveaux de profondeur maximum pour maintenir la clarté et la lisibilité. Si vous avez besoin de plus de niveaux, pensez à réorganiser le contenu pour faciliter la navigation et la compréhension des utilisateurs.

  • Toute liste, y compris les listes imbriquées, doit comporter entre deux et sept entrées. En général, plus les informations de chaque entrée sont courtes, plus vous pouvez ajouter d'entrées tout en gardant la liste scannable. Si une liste comporte plusieurs entrées contenant des listes imbriquées, pensez à utiliser des sections ou des titres de bloc pour diviser l'élément entier en plusieurs blocs de consommables.

  • Les entrées de liste doivent être aussi scannables que possible. Évitez les blocs de texte qui peuvent être lus de manière à ce que les entrées de liste soient scannables.

  • Les entrées de liste doivent commencer par une lettre majuscule et les entrées de liste doivent être grammaticales parallèles. Par exemple, commencez chaque entrée par un nom ou un verbe :

    • Si toutes les entrées de liste sont des phrases complètes, terminez-les par des périodes.

    • Si toutes les entrées de liste sont des fragments de phrase, ne les terminez pas par des points.

  • Les entrées de la liste doivent être ordonnées de manière logique, par exemple par ordre alphabétique ou chronologique.

localisation

Reportez-vous à la section Écrivez pour un public international.

minimalisme

Reportez-vous à la section Écriture minimale.

chiffres

  • Utilisez les chiffres arabes pour 10 et tous les chiffres supérieurs à 10, à l'exception des numéros suivants :

    • Si vous commencez une phrase avec un nombre, utilisez un mot, pas un chiffre arabe.

    • Utilisez des mots (et non des chiffres) pour obtenir des chiffres approximatifs.

  • Utilisez des mots pour des nombres inférieurs à 10.

  • Si une phrase contient un mélange de nombres inférieurs à 10 et supérieurs à 10, utilisez des chiffres arabes pour tous les nombres.

  • Pour plus d'informations sur les conventions numériques, reportez-vous à la section "Guide des styles d'écriture Microsoft".

plagiat

Nous documentons les produits NetApp et l'interaction des produits NetApp avec des produits tiers. Nous ne documentons pas les produits tiers. Il n'est jamais nécessaire de copier/coller du contenu tiers dans nos documents, et nous ne devrions jamais le faire.

prérequis

Les prérequis identifient les conditions qui doivent exister ou les actions que les utilisateurs doivent avoir effectuées avant de démarrer la tâche en cours.

  • Identifiez la nature du contenu à l'aide d'un en-tête, par exemple « Conditions préalables », « avant de commencer » ou « avant de commencer ».

  • Utilisez la voix passive pour la formulation des prérequis s'il est logique de le faire :

    • « NFS ou CIFS doivent être configurés sur le cluster. »

    • « Vous devez disposer de l'adresse IP de gestion du cluster et du mot de passe pour que le compte utilisateur admin puisse ajouter le cluster à Cloud Manager. »

  • Précisez les prérequis si nécessaire : « NFS ou CIFS doivent être configurés sur le cluster. Vous pouvez configurer NFS et CIFS à l'aide de System Manager ou de l'interface de ligne de commandes. »

  • Envisagez d'autres façons de présenter les informations, par exemple s'il serait approprié de redire le contenu comme première étape de la tâche en cours :

    • Condition préalable : « vous devez disposer des autorisations requises avant de déployer votre premier cluster. »

    • Étape : « fournissez les autorisations requises pour déployer votre premier cluster. »

précédent (par rapport à « avant », « précédent » ou « précédent »)

  • Si possible, remplacer « antérieur » par « antérieur ».

  • Si vous ne pouvez pas utiliser "avant", utilisez "précédent" comme adjectif pour faire référence à quelque chose qui s'est produit plus tôt dans le temps ou avec un ordre plus important.

  • Utilisez « précédent » pour indiquer quelque chose qui s'est produit à un moment non spécifié plus tôt.

  • Utilisez « précédent » pour indiquer un événement qui s'est produit immédiatement au préalable.

ponctuation

Privilégier la simplicité. En général, plus la ponctuation incluse dans une phrase est grande, plus il faut comprendre de cellules cérébrales.

  • Utilisez une virgule série (virgule Oxford) avant la conjonction (« et » ou « ou ») dans une liste narrative de trois éléments ou plus.

  • Limitez l'utilisation de points-virgules et de points-virgules.

  • Sauf mention contraire, suivez les conventions de grammaire, de ponctuation et d'orthographe détaillées dans :

depuis

Utiliser « depuis » pour indiquer un passage de temps. N'utilisez pas « depuis » pour dire « parce ».

orthographe

Sauf mention contraire, suivez les conventions de grammaire, de ponctuation et d'orthographe détaillées dans :

qui (par rapport à « qui » ou « qui »)

  • Utilisez « ça » (sans virgule de fin) pour introduire des clauses qui sont nécessaires pour que la phrase ait du sens.

  • Utilisez "cela" même si la phrase est claire en anglais sans elle: "Vérifier que l'ordinateur est éteint."

  • Utilisez « lequel » (avec une virgule de fin) pour introduire des clauses qui ajoutent des informations de support mais ne sont pas nécessaires pour que la phrase ait du sens.

  • Utilisez le terme « qui » pour présenter des clauses faisant référence aux personnes.

marques commerciales

Nous n'incluons pas de symboles de marque commerciale dans la plupart de notre contenu technique, car les mentions légales dans nos modèles sont suffisantes. Cependant, nous suivons toutes les règles d'utilisation lors de l'utilisation "Conditions de marques commerciales de NetApp":

  • Utilisez des termes de marque de commerce (avec ou sans le symbole) uniquement en tant qu'adjectifs, jamais en tant que noms, verbes ou verbes verbaux.

  • N'utilisez pas d'abréviations, de césure ou d'italique pour les termes des marques commerciales.

  • Ne pas plurialiser les termes des marques déposées. Si une forme plurielle est requise, utilisez le nom de marque déposée comme adjectif qui modifie un nom pluriel.

  • N'utilisez pas une forme possessive de terme de marque déposée. Vous pouvez utiliser la forme possessive de noms d'entreprise, comme NetApp, lorsque les noms sont utilisés de manière générale, plutôt que comme conditions de marque de commerce.

interface utilisateur

Lorsque vous documentez une interface utilisateur, utilisez l'interface autant que possible pour guider l'utilisateur.

Directives générales

Utilisez un style simple et mimimal lors de la documentation des IU.

Details

  • Supposons que l'utilisateur utilise l'interface lors de la lecture du contenu :

    • Ne pas guider l'utilisateur pas à pas dans un assistant ou un écran. N'appelez que les éléments importants qui ne sont pas apparents de l'interface.

    • N'incluez pas « cliquez sur OK », « cliquez sur Enregistrer » ou « le volume est créé », ni tout autre élément évident pour quelqu'un qui effectue la tâche.

    • Supposer le succès. Sauf si vous pensez qu'une opération échoue la plupart du temps, ne documentez pas le chemin d'échec. Supposons que l'interface fournit un guidage approprié.

  • N'utilisez pas du tout « clic ». Utilisez toujours "Select" car ce mot couvre la souris, le toucher, le clavier et toute autre manière de faire un choix.

  • Concentrez-vous sur un workflow qui répond à l'utilisation d'un client et sur la mise en place d'un utilisateur dans l'interface pour démarrer le workflow.

  • Documentez toujours la meilleure façon d'atteindre l'objectif de l'utilisateur.

  • Si le flux de travail nécessite une décision importante, assurez-vous de documenter une règle de décision.

  • Utilisez le nombre minimum d'étapes nécessaires à la plupart des utilisateurs la plupart du temps.

Dénomination des éléments de l'interface utilisateur

Évitez de fournir des informations sur le niveau de granularité qui nécessite de nommer les éléments de l'interface utilisateur.

Details

Utilisez l'interface pour guider l'utilisateur à travers les détails de l'interaction. Si vous devez obtenir ce spécifique, nommez-le sur l'élément. Par exemple, « sélectionnez le volume souhaité » ou « sélectionnez « utiliser le volume existant ». Il n'est pas nécessaire de nommer des menus, des boutons radio ou des cases à cocher, il suffit d'utiliser l'étiquette.

Pour les icônes que les utilisateurs doivent sélectionner, utilisez une image de l'icône. N'essayez pas de le nommer. Cette règle s'applique à des icônes comme la flèche, le crayon, l'engrenage, le kabob, le hamburger, et ainsi de suite.

Représentant les étiquettes affichées

Suivez l'orthographe et la casse utilisées par l'interface utilisateur lors de l'identification des étiquettes.

Details

Si un libellé est suivi de points de suspension, ne pas inclure les points de suspension lors de la désignation de l'objet. Encouragez les développeurs à utiliser la capitalisation de style titre pour les étiquettes de l'interface utilisateur, afin de faciliter l'écriture à leur sujet.

Utilisation des captures d'écran

Utilisez les captures d'écran avec parcimonie.

Details

Une capture d'écran occasionnelle (« capture d'écran ») permet aux utilisateurs de s'assurer qu'ils se trouvent au bon endroit dans une interface lors du démarrage ou du changement d'interfaces au cours d'un flux de travail. N'utilisez pas les captures d'écran pour afficher les données à saisir ou la valeur à sélectionner.

pendant (par rapport à « bien »)

  • Utilisez « pendant » pour indiquer une situation dans le temps.

  • Utilisez « quoique » pour représenter une activité qui se produit presque au même moment ou peu après une autre activité.