⚠️ Traduction non officielle - Cette documentation est une traduction communautaire non officielle de Docker.

Directives pour écrire des guides d'utilisation Docker

Table des matières

Ce guide fournit des instructions et des meilleures pratiques pour écrire des guides d'utilisation de style tutoriel qui aident les utilisateurs à atteindre des objectifs spécifiques en utilisant Docker. Ces guides seront mis en avant dans la section guides du site web, aux côtés de nos manuels de produits et matériaux de référence.

Notre documentation est écrite en Markdown, avec des métadonnées YAML en front matter. Nous utilisons Hugo pour construire le site web. Pour plus d'informations sur comment écrire du contenu pour la documentation Docker, référez-vous à notre CONTRIBUTING.md.

Objectif des guides

Nos guides d'utilisation visent à :

  • Éduquer les utilisateurs sur comment tirer parti de Docker dans divers contextes.
  • Fournir une expérience pratique et concrète à travers des tutoriels étape par étape.
  • Aider les utilisateurs à atteindre des objectifs spécifiques pertinents à leurs intérêts ou projets.

Public

  • Niveaux d'expérience : Des débutants aux utilisateurs avancés.
  • Rôles : Développeurs, administrateurs système, ingénieurs DevOps, et plus.
  • Technologies : Divers langages de programmation et frameworks.

Métadonnées pour les guides

Chaque guide doit inclure une section de métadonnées au début du document. Ces métadonnées aident les utilisateurs à découvrir et filtrer les guides basés sur leurs intérêts et besoins.

Format d'exemple de métadonnées 

---
title: Déployer un modèle d'apprentissage automatique avec Docker
linkTitle: Docker pour le déploiement ML
description: Apprenez à conteneuriser et déployer un modèle d'apprentissage automatique en utilisant Docker.
summary: |
  Ce guide vous guide à travers les étapes pour conteneuriser un modèle d'apprentissage
  automatique et le déployer en utilisant Docker, permettant des solutions d'IA
  évolutives et portables.
tags: [apprentissage-automatique, déploiement]
languages: [python]
params:
  time: 30 minutes
---

Champs de métadonnées

  • title (requis) : Le titre principal du guide en casse de phrase.
  • linkTitle (optionnel) : Un titre plus court utilisé dans les menus de navigation.
  • description (requis) : Une description concise à des fins SEO.
  • summary (requis) : Un aperçu bref du contenu du guide.
  • languages * (optionnel) : Liste des langages de programmation utilisés.
  • tags * (optionnel) : Domaines ou domaines d'expertise couverts.
  • params
    • time (optionnel) : Temps estimé de lecture ou d'achèvement.

* Appliquez au moins une des taxonomies languages ou tags. Les valeurs sont utilisées pour associer la page aux options de filtre sur la page d'accueil des guides.

Structure du document

Nos guides mettent l'accent sur l'apprentissage par la pratique. Selon le type de guide, la structure peut varier pour mieux s'adapter au contenu et fournir une expérience d'apprentissage fluide.

Tous les guides vivent directement sous le répertoire content/guides/ dans le dépôt de documentation Docker. Les guides peuvent être soit une seule page soit plusieurs pages. Dans le cas de guides multi-pages, chaque page est une étape dans un flux de travail séquentiel.

Si vous créez un guide d'une seule page, créez un seul fichier markdown dans le répertoire guides :

# Créer le fichier
touch content/guides/my-docker-guide.md
# ou si vous avez Hugo installé :
hugo new content/guides/my-docker-guide.md

Pour créer un guide multi-pages, créez un répertoire où chaque page est un fichier markdown, avec un fichier _index.md représentant l'introduction au guide.

# Créer la page d'index pour le guide
mkdir content/guides/my-docker-guide.md
touch content/guides/my-docker-guide/_index.md
# ou si vous avez Hugo installé :
hugo new content/guides/my-docker-guide/_index.md

Ensuite, créez les pages pour le guide sous content/guides/<dir>/<page>.md selon les besoins. Les métadonnées vivent sur la page _index.md (vous n'avez pas besoin d'assigner des métadonnées aux pages individuelles).

Guides pour des frameworks ou langages spécifiques

Pour les guides qui démontrent comment utiliser Docker avec un framework particulier ou un langage de programmation, considérez le plan suivant :

  1. Introduction
    • Introduisez brièvement le framework ou le langage dans le contexte de Docker.
    • Expliquez ce que l'utilisateur accomplira à la fin du guide.
    • Listez les logiciels, outils et connaissances requis.
  2. Configuration de développement
    • Guidez l'utilisateur à travers la configuration d'un environnement de développement.
    • Incluez des instructions sur l'écriture ou l'obtention de code d'exemple.
    • Montrez comment exécuter des conteneurs pour le développement local.
  3. Construction de l'application
    • Expliquez comment créer un Dockerfile adapté à l'application.
    • Fournissez des instructions étape par étape pour construire l'image Docker.
    • Si applicable, montrez comment tester l'application en utilisant Docker.
  4. Déploiement avec Docker
    • Montrez comment exécuter l'application dans un conteneur Docker.
    • Discutez des options de configuration et des meilleures pratiques.
  5. Meilleures pratiques et conclusions
    • Offrez des conseils pour optimiser l'utilisation de Docker avec le framework ou le langage.
    • Résumez les points clés, suggérez les prochaines étapes et les lectures supplémentaires.

Guides de cas d'usage

Pour les guides axés sur l'accomplissement d'un objectif spécifique ou d'un cas d'usage avec Docker (par exemple, déployer un modèle d'apprentissage automatique), utilisez un plan flexible qui assure un flux logique.

Le plan suivant est un exemple. La structure doit être ajustée pour mieux s'adapter au contenu et assurer une progression claire et logique. Selon le sujet de votre guide de cas d'usage, la structure exacte variera.

  1. Introduction
    • Décrivez le problème ou l'objectif.
    • Expliquez les avantages d'utiliser Docker dans ce contexte.
  2. Prérequis
    • Listez les outils, technologies et connaissances préalables requis.
  3. Configuration
    • Fournissez des instructions pour configurer l'environnement.
    • Incluez toutes les étapes de configuration nécessaires.
  4. Implémentation
    • Guidez le processus étape par étape.
    • Utilisez des extraits de code et des explications pour illustrer les points clés.
  5. Exécution ou déploiement de l'application
    • Guidez l'utilisateur sur comment exécuter ou déployer la solution.
    • Discutez de toutes les étapes de vérification pour assurer le succès.
  6. Conclusion
    • Récapitulez ce qui a été accompli.
    • Suggérez des lectures supplémentaires ou des sujets avancés.

Code d'exemple

Si vous créez un dépôt d'exemple avec du code source pour accompagner votre guide, nous encourageons fortement à publier ce dépôt sous l'organisation dockersamples sur GitHub. Publier votre code source sous cette organisation, plutôt que votre compte personnel, assure que le code source reste accessible aux mainteneurs du site de documentation après publication. En cas de bug ou de problème dans le guide, l'équipe de documentation peut plus facilement mettre à jour le guide et son dépôt d'exemple correspondant.

Héberger les exemples dans l'espace de noms officiel des échantillons aide aussi à sécuriser la confiance avec les utilisateurs qui lisent le guide.

Publier un dépôt sous dockersamples

Pour publier votre dépôt sous l'organisation dockersamples, utilisez le modèle dockersamples pour initier un dépôt d'échantillon sous votre espace de noms personnel. Quand vous avez fini de rédiger votre contenu et ouvert votre pull request pour la documentation, nous pouvons transférer le dépôt vers l'organisation dockersamples.

Style d'écriture

Utilisez la casse de phrase pour tous les en-têtes et titres. Cela signifie que seuls le premier mot et les noms propres sont capitalisés.

Voix et ton

  • Clarté et concision : Utilisez un langage simple et des phrases courtes pour transmettre l'information efficacement.
  • Voix active : Écrivez à la voix active pour engager le lecteur (par exemple, "Exécutez la commande" au lieu de "La commande devrait être exécutée").
  • Cohérence : Maintenez un ton et une terminologie cohérents tout au long du guide.

Pour des directives détaillées, référez-vous à notre documentation sur la voix et le ton.

Conventions de formatage

  • En-têtes : Utilisez H2 pour les sections principales et H3 pour les sous-sections, en suivant la casse de phrase.
  • Exemples de code : Fournissez des extraits de code complets et fonctionnels avec coloration syntaxique.
  • Listes et étapes : Utilisez des listes numérotées pour les étapes séquentielles et des puces pour les informations non séquentielles.
  • Emphase : Utilisez le gras pour les éléments d'interface utilisateur (par exemple, Bouton), et l'italique pour l'emphase.
  • Liens : Utilisez un texte de lien descriptif (par exemple, Installer Docker).

Pour plus de détails, consultez nos directives de formatage de contenu et règles de grammaire et de style.

Meilleures pratiques

  • Tester toutes les instructions
    • Assurez-vous que tout le code et les commandes fonctionnent comme attendu.
    • Vérifiez que le guide peut être suivi avec succès du début à la fin.
  • Pertinence
    • Concentrez-vous sur des applications et scénarios du monde réel.
    • Gardez le contenu à jour avec les dernières versions de Docker.
  • Conseils de dépannage
    • Anticipez les problèmes courants et fournissez des solutions ou des références.
  • Aides visuelles
    • Incluez des captures d'écran ou des diagrammes où ils améliorent la compréhension.
    • Ajoutez des légendes et du texte alternatif pour l'accessibilité.
  • Outils tiers
    • Évitez d'exiger que l'utilisateur installe des outils tiers ou modifie son environnement de développement local.
    • Préférez utiliser des outils et méthodes conteneurisés le cas échéant (par exemple docker exec).
    • Certains outils sont raisonnables à supposer comme installés ou prérequis pour les guides, comme Node.js et npm. Utilisez votre meilleur jugement.

Ressources supplémentaires

Processus de soumission

  • Proposition

    • Créez un problème sur le dépôt GitHub de documentation Docker avec une demande d'ajout d'un nouveau guide.

    • Une fois la proposition acceptée, commencez à écrire votre guide en forkant le dépôt et en créant une branche pour votre travail.

      Note

      Évitez de contribuer depuis la branche main de votre fork, car cela rend plus difficile pour les mainteneurs de vous aider à corriger tous les problèmes qui peuvent survenir.

  • Révision

    • Relisez votre guide pour la grammaire, la clarté et l'adhérence aux directives.
    • Une fois votre brouillon prêt, créez une pull request, avec une référence au problème original.
    • L'équipe de documentation Docker et les experts en la matière réviseront votre soumission et fourniront des commentaires sur la pull request directement.

  • Publication

    • Votre guide sera publié sur le site web de documentation Docker quand les réviseurs auront approuvé et fusionné votre pull request.

Merci de contribuer à la communauté Docker. Votre expertise aide les utilisateurs du monde entier à exploiter la puissance de Docker.