Directives de rédaction technique de DigitalOcean

DigitalOcean est ravi de continuer à enrichir sa collection d'articles techniques liés à l'administration de serveurs et au génie logiciel. Pour garantir la qualité et le style des articles DigitalOcean, nous avons développé les directives suivantes.

Ce guide comporte trois sections:

Style, notre approche de haut niveau pour la rédaction de tutoriels techniques
Structure, une explication de notre mise en page et de notre contenu
Formatting and Terminology, une référence de démarque et de terminologie

Pour être publiés rapidement, les auteurs de la communauté DigitalOcean doivent lire l'intégralité des sections relatives au style et à la structure. Nostemplates sont utiles comme point de départ pour un article, et la section de mise en forme de ce guide ainsi que nosMarkdown previewer peuvent être utilisées comme références lors de l'écriture. Nous avons également untechnical best practices guide pour nos recommandations axées sur la technologie.

Style

Les articles de DigitalOcean doivent être:

Complet et écrit pour tous les niveaux d'expérience

Nos articles sont écrits pour être aussi clairs et détaillés que possible, sans faire de suppositions sur les connaissances de base du lecteur.

Nous incluons explicitement chaque commande dont un lecteur a besoin pour passer de sa première connexion SSH sur un tout nouveau serveur à la dernière configuration opérationnelle. Nous fournissons également aux lecteurs toutes les explications et informations de base dont ils ont besoin pour comprendre le didacticiel. Le but est que nos lecteurs apprennent, pas seulement copient et collent.

Techniquement détaillé et correct

Tous nos tutoriels sont testés sur de nouveaux serveurs pour garantir leur fonctionnement à partir de zéro. Chaque commande doit avoir une explication détaillée, y compris des options et des indicateurs si nécessaire. Lorsque vous demandez au lecteur d’exécuter une commande ou de modifier un fichier de configuration, expliquez d’abord ce qu’il fait ou pourquoi il apporte ces modifications.

Pratique, utile et autonome

Une fois qu'un article est terminé, les lecteurs doivent avoir installé ou configuré quelque chose du début à la fin. Nous mettons l'accent sur une approche pratique: à la fin d'un article, nous devrions laisser au lecteur un environnement utilisable ou un exemple sur lequel s'appuyer.

Pour l'auteur, cela signifie que son article doit couvrir son sujet de manière approfondie et, si nécessaire, créer un lien vers un autre article de DigitalOcean afin de définir les conditions préalables. Les auteurs ne doivent pas envoyer de lecteurs hors site pour recueillir des informations qui pourraient facilement être ajoutées à l’article.

Sympathique mais formel

Nos tutoriels visent un ton amical mais formel. Cela signifie que les articles n'incluent pas de jargon, de memes ou de blagues excessives. Cela signifie également que, contrairement aux billets de blog, nous n'utilisons pas la première personne du singulier (par exemple, "Je pense …"). Au lieu de cela, nous utilisons la première personne du pluriel (par ex. «Nous installerons…) ou une deuxième personne (par exemple "Vous allez configurer…").

Structure

Les didacticiels DigitalOcean ont une structure cohérente comprenant les sections suivantes:

Titre
introduction
Objectifs (facultatif)
Conditions préalables
Étape 1 - Faire la première chose
Étape 2 - Faire la prochaine chose
…
Étape n - Faire la dernière chose
Conclusion

Nosarticle templates ont cette mise en page dans Markdown, que vous pouvez utiliser comme point de départ pour vos propres articles. LeFormatting section of this guide a plus de détails sur nos conventions de formatage.

Titre

Un titre typique suit ce format:How To <Accomplish a Task> with <Software> on <Distro>.

Lorsque vous écrivez votre titre, réfléchissez bien à ce que le lecteur va accomplir en suivant votre tutoriel. Essayez d’inclure l’objectif du didacticiel dans le titre, pas seulement les outils que le lecteur utilisera pour atteindre cet objectif.

Par exemple, si votre didacticiel concerne l'installation de Caddy, l'objectif est probablementhost a website. Si votre tutoriel concerne l'installation de FreeIPA, l'objectif peut être deset up centralized Linux authentication. Titres qui incluent l'objectif (comme «https://www.digitalocean.com/community/tutorials/how-to-create-a-status-page-with-cachet-on-debian-8[Comment créer une page d'état avec Cachet sur Debian 8] ”) sont généralement plus informatifs pour le lecteur que les titres qui ne le sont pas (comme“ Comment installer et configurer Cachet sur Debian 8 ”).

Introduction et objectifs

La première section de chaque didacticiel est leIntroduction, qui est généralement de 1 à 3 paragraphes.
Le but de l'introduction est de répondre aux questions suivantes pour le lecteur:

Quel est le but du tutoriel? Qu'est-ce que le lecteur va accomplir s'il le suit?
Quel logiciel est impliqué et que fait chaque composant (brièvement)?
Quels sont les avantages d'utiliser ce logiciel dans cette configuration? Quelles sont certaines des raisons pratiques pour lesquelles le lecteur devrait suivre ce tutoriel?

Certains didacticiels utilisent la section facultativeGoals pour séparer le contexte, l'explication d'arrière-plan et la motivation du didacticiel des détails de la configuration finale. Vous ne devez utiliser cette section que si votre didacticiel nécessite plusieurs serveurs, dispose d'une pile logicielle volumineuse ou a un autre objectif, une méthode ou un résultat particulièrement compliqué.

Quelques bons exemples incluentthis Prometheus tutorial’s introduction etthis Pydio tutorial’s goals.

Conditions préalables

Les sectionsPrerequisites des didacticiels DigitalOcean ont un format et un objectif très spécifiques.

Le but est de préciserexactly ce que le lecteur devrait avoir ou faire avant de suivre le didacticiel en cours. Le format est une liste à puces que le lecteur peut utiliser comme liste de contrôle. Chaque puce doit être liée à un didacticiel DigitalOcean existant couvrant le contenu nécessaire. Cela vous permet de vous fier au contenu existant connu pour fonctionner au lieu de partir de zéro.

Les points communs les plus courants incluent:

Nombre de serveurs nécessaires, y compris la distribution, la configuration initiale du serveur et toutes les options supplémentaires nécessaires (telles que la mémoire requise, les clés API DO, IPv6 ou la mise en réseau privée).
Installation et configuration du logiciel.
Paramètres DNS requis ou certificats SSL.
Comptes d'utilisateurs supplémentaires tels que GitHub, Facebook, Twitter ou d'autres services dont votre lecteur aura besoin.

Lorsque vous testez votre didacticiel, assurez-vous de suivre tous les didacticiels prérequis exactement tels qu'ils ont été écrits, afin que tout le monde utilise le même point de départ. Si vous avez modifié une variable ou complété une étape facultative à partir de l’un des prérequis, assurez-vous de le noter.

Nos didacticiels d’administration système permettent au lecteur de passer d’un récent déploiement d’une image de la distribution vanilla à une configuration opérationnelle. Ils doivent donc commencer par la première connexion SSH au serveur ou inclure un didacticiel préalable.

Vous pouvez voir de bons exemples de prérequis pour:

Serveurs Ubuntu 16.04, installation de logiciels et enregistrements DNS enthis Minio tutorial’s prerequisites.
Serveurs CentOS 7 et enregistrements DNS enthis FreeIPA tutorial’s prerequisites.
Serveurs Debian 8 avec besoins en mémoire et configuration logicielle en utilisant des étapes partielles d'autres tutoriels dansthis Cachet tutorial’s prerequisites.
Gestion de plusieurs serveurs avec installation du logiciel enthis Nagios and Alerta tutorial’s prerequisites.

Pas

Les sectionsStep sont les parties de votre didacticiel où vous décrivez ce que le lecteur doit faire.

Commencez chaque étape par une phrase d'introduction décrivant ce que l'étape couvre et son rôle dans la réalisation de l'objectif général du didacticiel. Terminez chaque étape avec une phrase de transition décrivant ce que le lecteur a accompli et où il va ensuite. Évitez de répéter le titre de l’étape dans ces introductions et transitions et ne commencez ou ne terminez pas les étapes avec des instructions, des commandes ou des sorties sans contexte.

Toutes les commandes d'une étape doivent être sur leur propre ligne dans leur propre bloc de code et chaque commande doit être précédée d'une description. De même, introduisez toujours un fichier ou un script en décrivant son objectif général, puis expliquez les modifications que le lecteur apportera au fichier. Sans ces explications, les lecteurs ne pourront pas personnaliser, mettre à jour ou dépanner leur serveur à long terme.

Lescustom Markdown and formatting guidelines de DigitalOcean sont conçus pour rendre les instructions de nos didacticiels aussi faciles à lire que possible. This Docker Swarm tutorial est un bon exemple d'utilisation de notre Markdown personnalisé pour distinguer les commandes exécutées sur plusieurs serveurs différents, ainsi que localement.

Conclusion

LesConclusion doivent résumer ce que le lecteur a accompli en suivant votre tutoriel. Il devrait également décrire ce que le lecteur peut faire ensuite. Cela peut inclure une description des cas d'utilisation ou des fonctionnalités que le lecteur peut explorer, des liens vers d'autres didacticiels de DigitalOcean avec une configuration ou une configuration supplémentaire, ainsi qu'une documentation externe.

Quelques bons exemples incluentthis LXD tutorial’s conclusion, https: //www.digitalocean.com/community/tutorials/how-to-monitor-cpu-use-on-digitalocean-droplets#conclusion [conclusion de ce tutoriel de surveillance CPU], et this Mosquitto tutorial’s conclusion.

Mise en page

Les didacticiels DigitalOcean sont formatés dans le langage de balisage Markdown. Daring Fireball publie un guide Markdown complet si vous ne le connaissez pas. DigitalOcean utilise également descustom Markdown. Des exemples de notre démarque personnalisée se trouvent dans les sections appropriées ci-dessous.

En-têtes

Chaque section de nos tutoriels a un en-tête correspondant: le titre doit être un en-tête H1; l'introduction devrait être un en-tête H3; les objectifs, les conditions préalables, les étapes et la conclusion doivent avoir un en-tête H2. Vous pouvez voir ce format dans nosMarkdown article templates.

Pour les didacticiels de procédure, les en-têtes d'étape doivent inclure des numéros d'étape (numériques) suivis d'un tiret em (—). Les en-têtes d'étape doivent également utiliser le gérondif, qui sont des mots-ing. Un exemple d'en-tête d'étape estStep 1 — Installing Nginx.

Utilisez les en-têtes H3 avec modération et évitez les en-têtes H4. Si vous devez utiliser des sous-en-têtes, assurez-vous qu'il existe au moins deux en-têtes de ce niveau dans cette section du didacticiel. Vous pouvez également envisager de faire plusieurs étapes à la place.

Formatage au niveau ligne

Bold text doit être utilisé pour:

Texte visible de l'interface graphique
Noms d'hôte et noms d'utilisateur, commewordpress-1 ousammy
Listes de termes
Accentuation lors du changement de contexte pour une commande, comme le changement de serveur ou d'utilisateur

Italics ne doit être utilisé que lors de l'introduction de termes techniques. Par exemple, le serveur Nginx sera nosload balancer.

Le formatage de code en ligne doit être utilisé pour:

Noms de commandes, commeunzip
Noms de paquet, commemysql-server
Commandes optionnelles
Noms et chemins de fichiers, comme~/.ssh/authorized_keys
Exemples d'URL, commehttp://your_domain
Ports, comme:3000
Appuis sur les touches, qui doivent être en MAJUSCULES et utiliser un symbole plus, **, si les touches doivent être enfoncées simultanément, comme `+ ENTER` ouCTRL+C

Blocs de code

Les blocs de code doivent être utilisés pour:

Commandes que le lecteur doit exécuter pour compléter le didacticiel
Fichiers et scripts
Sortie du terminal
Dialogues interactifs en texte

Les extraits et omissions dans les fichiers peuvent être indiqués par des ellipses (…). Si la plupart des fichiers peuvent rester avec les paramètres par défaut, il est généralement préférable d’afficher uniquement la section à modifier.

Préfixes de bloc de code

N'incluez pas l'invite de commande dans le bloc de code. A la place, utilisez le Markdown personnalisé de DigitalOcean pour les commandes utilisateur non root, les commandes utilisateur root et les préfixes personnalisés, respectivement:

```command
sudo apt-get update
```

```super_user
adduser sammy
```

```custom_prefix(mysql>)
FLUSH PRIVILEGES;
```

Voici à quoi ressemblent les exemples précédents lors du rendu:

sudo apt-get update

adduser sammy

FLUSH PRIVILEGES;

Étiquettes de bloc de code

DigitalOcean’s Markdown inclut également des étiquettes et des étiquettes secondaires. Vous pouvez ajouter des étiquettes aux blocs de code en ajoutant une ligne avec[label Label text] ou[secondary_label Secondary label text] n'importe où dans le bloc.

Utilisez des étiquettes pour marquer les blocs de code contenant le contenu d'un fichier avec un nom de fichier. Utilisez des étiquettes secondaires pour marquer la sortie du terminal.

Les étiquettes ressemblent à ceci lors du rendu:

Ceci est le texte de l'étiquette

This is one line of the file
This is another line of the file
. . .
This is a line further down the file

Exemple d'étiquette secondaire:

This is the secondary label textThis is some output from a command

Couleurs de l'environnement du bloc de code

Le Markdown de DigitalOcean vous permet de colorer l'arrière-plan d'un bloc de code en ajoutant une ligne avec[environment name] n'importe où dans le bloc. Les options pourname sontlocal,second,third,fourth etfifth.

Voici un exemple de commande de serveur local:

ssh root@your_server_ip

Voici des exemples de commandes de serveur non principal, utiles pour les configurations multi-serveurs:

echo "Secondary server"

echo "Third server"

echo "Fourth server"

echo "Fifth server

Notes et avertissements

L'analyseur DigitalOcean Markdown permet d'utiliser des blocs de code personnalisésnote etwarning pour afficher du texte très important.

Voici un exemple de note et d’avertissement Markdown (il s’agit d’une image):

Notes and Warnings

Voici le résultat rendu:

[.note] #Note: Ceci est une note.
#

[.warning] #Warning: Ceci est un avertissement.
#

Variables

Mettez en surbrillance tous les éléments devant être modifiés par le lecteur, tels que des exemples d’URL ou de lignes modifiées dans les fichiers de configuration. Vous pouvez le faire en entourant le mot ou la ligne de notre<^> Markdown personnalisé. Notez que vous ne pouvez pas surligner plusieurs lignes avec une paire de symboles. Vous devez donc surligner chaque ligne individuellement.

Si vous référencez une variable dans un contexte où vous utiliseriez normalement également le formatagein-line code, vous devez utiliserboth styles. Assurez-vous que votre didacticiel est aussi accessible que possible en utilisant un langage comme «en surbrillance dans le bloc de code précédent» au lieu de «en surbrillance en rouge ci-dessus».

Évitez un langage comme «surligné en rouge ci-dessous»

Images et autres actifs

Les images peuvent rapidement illustrer un point ou apporter des éclaircissements supplémentaires dans une étape. Utilisez des images pour les captures d’écran des interfaces graphiques, les dialogues interactifs et les diagrammes des configurations du serveur. N’utilisez pas d’images pour les captures d’écran de code, les fichiers de configuration, la sortie ou tout élément pouvant être copié et collé dans l’article.

Si vous incluez des images dans votre tutoriel, suivez les instructions ci-dessous:

Incluez du texte alt descriptif pour que les lecteurs utilisant un lecteur d'écran puissent utiliser le texte alt plutôt que l'image.
Utilisez le format de fichier.png
Héberger des images surimgur
Rendre l'image avec une hauteur aussi courte que possible

Si vous créez une maquette de diagramme pour votre tutoriel, nous créerons un diagramme dans le style DigitalOcean. Nous téléchargerons également toutes les images sur les serveurs DigitalOcean au moment de la publication.

Voici un exemple de Markdown pour inclure des images dans votre tutoriel:

![Alt text for screen readers](http://imgur.com/your_image_url)

Parfois, vous souhaiterez que le lecteur ait accès à un fichier de configuration trop long pour être affiché dans le corps principal du didacticiel. DigitalOcean hébergera ce fichier sur notre serveur d'actifs. Vous pouvez utiliser le formatage de lien standard pour lier le fichier.

Terminologie

Utilisateurs, noms d'hôte et domaines

Notre exemple de nom d'utilisateur par défaut estsammy. Vous pouvez également choisir quelque chose de descriptif lorsque cela est utile, commewebdav-kai ounsd.

your_server est le nom d'hôte par défaut, bien que vous soyez encouragé à choisir quelque chose de descriptif, en particulier dans les configurations multi-serveurs, commedjango_replica_1.

your_domain est le domaine par défaut. Pour les configurations multi-serveurs, vous pouvez choisir quelque chose commeprimary-1.your_domain oureplica-1.your_domain. Alors queexample.com est un domaine valide pour la documentation, l'utilisation deyour_domain dans les didacticiels indique plus clairement que le lecteur doit changer le domaine dans les exemples.

Utilisez la surbrillance lorsque vous utilisez ceux-ci dans les fichiers de configuration, comme ceci:

exemple de fichier de configuration

ip: your_server_ip
domain: primary-1.your_domain

Cela indique clairement aux lecteurs qu’il ya quelque chose à changer.

Adresses IP et URL

your_server_ip, avec formatage de code en ligne et mise en évidence des variables, est le moyen par défaut d'afficher une adresse IP. Vous pouvez afficher plusieurs adresses IP avec des noms tels queprimary_private_ip etreplica_private_ip. Si vous avez besoin d'illustrer des adresses IP plus réalistes, utilisez une adresse dans lesone of the two blocks reserved for documentation as per RFC-5737. Plus précisément, nous recommandons203.0.113.0/24 par exemple les adresses publiques et198.51.100.0/24 par exemple les adresses privées.

Les exemples d’URL contenant une variable que le lecteur doit personnaliser doivent utiliser le formatage du code avec la variable en surbrillance. Nous utilisons par défautyour_domain. commehttps://your_domain:3000/simple/ ouhttp://your_server_ip/. Cependant, les liens dynamiques devraient plutôt utiliser le style de lien standard Markdown sans mise en forme supplémentaire.

Logiciel

Utilisez la capitalisation du nom du logiciel sur le site officiel. Si le site Web du produit ne correspond pas à sa capitalisation, soyez cohérent dans un seul article.

Lien vers la page d'accueil du logiciel lorsque vous mentionnez le logiciel pour la première fois.

Configurations multi-serveurs

Pour des raisons techniques, utilisez la terminologie du projet pour les configurations multi-serveurs. S'il vous plaît soyez clair que les termes viennent du projet. Par exemple: «Le projet Django fait référence au serveur d'origine en tant queprimary et au serveur secondaire en tant quereplica. Le projet MySQL fait référence au serveur d'origine en tant quemaster et au serveur secondaire en tant queslave. »

Lorsque vous discutez des architectures multi-serveurs de manière plus abstraite, utilisez les termesprimary etreplica oumanager etworker.

Meilleures pratiques techniques

Notre guidetechnical best practices guide contient plus de conseils qui vous aideront à créer des didacticiels cohérents et de qualité qui aideront nos lecteurs.

Suivez ce lien versbecome a DigitalOcean author.

TOC