Guide de rédaction

Voici quelques instructions pour vous aider à présenter au mieux le contenu de votre tutoriel et permettre ainsi aux utilisateurs de se familiariser efficacement avec votre projet.

Fonctionnalités de Cloud Shell

  • Mise en page unique : les tutoriels sont présentés dans un panneau latéral (310 pixels de large) sur la droite de Google Cloud Console
  • Navigation : les utilisateurs peuvent parcourir le tutoriel à l'aide des boutons "Continuer" et "Précédent". Notez que si vous êtes sur une page correspondant à une étape déjà effectuée, le bouton "Continuer" est remplacé par "Suivant". Les utilisateurs ont également la possibilité de quitter le tutoriel en cliquant sur le bouton "Annuler le tutoriel" et de le reprendre plus tard, là où ils se sont arrêtés.
  • Code accessible : vous pouvez inclure des extraits de code dans votre tutoriel. Ceux-ci seront mis en forme avec l'icône Icône de copie, qui permet aux utilisateurs d'effectuer facilement un copier-coller directement dans Cloud Shell.

Session de console avec un tutoriel ouvert

Une session de console avec le volet de tutoriel ouvert sur le côté droit. Les utilisateurs peuvent copier le code directement dans Cloud Shell à l'aide de l'icône correspondante, et passer d'une page à l'autre en cliquant sur "Précédent" et "Continuer".

Style d'écriture

  • Utilisez des termes simples : les tutoriels doivent être informatifs et utiles, mais pas trop formels.
  • Adressez-vous à l'utilisateur : privilégiez les pronoms à la deuxième personne (utilisez vous, votre, etc. et évitez nous, notre, etc.).
  • Expliquez les causes et les effets : lorsque vous demandez aux utilisateurs d'effectuer une étape, expliquez le raisonnement qui sous-tend l'action et le résultat attendu.
  • Définissez des objectifs clairs : avant de rédiger le contenu de votre tutoriel, définissez l'objectif souhaité pour vos utilisateurs. Concevez votre tutoriel en gardant toujours cet objectif à l'esprit.
Version initiale Version corrigée Amélioration
Sur la page suivante, nous expliquerons comment concevoir un tutoriel. Passez à l'étape suivante pour commencer à configurer votre tutoriel. Met l'accent sur l'utilisateur et privilégie la voix active

Utilise un langage courant

Exécutez cette commande :

``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ```

Pour afficher un tableau intitulé "Projets", qui liste tous vos projets et leurs ID, exécutez la commande suivante : ```gcloud projects list --format="table[box,title=Projects](name, projectId)"``` Explique d'emblée le raisonnement afin de définir des attentes claires concernant le résultat
Let's get started! Let's get started!

Ce guide vous explique comment créer votre propre tutoriel interactif. Il vous accompagne également dans la création d'un bouton que les utilisateurs pourront activer pour démarrer facilement votre tutoriel.

Présentation claire des sujets abordés dans le tutoriel

À garder à l'esprit lors de la rédaction du contenu

Bonnes pratiques

  • Soyez bref : le volet du tutoriel offre un espace restreint. Vous ne pouvez donc présenter qu'une quantité limitée d'informations à la fois. Évitez les longs paragraphes demandant beaucoup de concentration et de défilements verticaux. Segmentez les informations en petits morceaux.

    • Ne dépassez pas cinq étapes et trois extraits de code par page.

    • Les paragraphes devraient idéalement être de cinq lignes ou moins, et devraient traiter d'un seul concept bien défini.

    • S'il n'est pas possible de raccourcir une page, essayez de ne pas dépasser deux fois la longueur du volet.

    • Les blocs de code et de terminal doivent être suffisamment petits pour être lisibles :

      • Optez pour 10 lignes ou moins.
      • Essayez de vous en tenir à 80 caractères ou moins par ligne afin de limiter le défilement horizontal.
      • Évitez les extraits de code à plusieurs commandes pour que les utilisateurs n'aient pas à les copier-exécuter en bloc.
  • Page d'introduction : commencez votre tutoriel par une introduction.

    • Définissez les attentes : expliquez brièvement ce que vos utilisateurs retiendront de ce tutoriel.
    • Indiquez la durée estimée : estimez approximativement le temps requis pour terminer le tutoriel. Essayez de ne pas dépasser 15 minutes. Si votre tutoriel est plus long (ou comporte plus de 15 pages particulièrement denses), envisagez de le diviser en une série de tutoriels de plus petite taille.
    • Soyez clair dès le départ : indiquez les ressources préalables requises ou les accès que les utilisateurs pourraient avoir besoin de configurer pour suivre le tutoriel sans interruption.
    Exemple

    ## C'est parti !

    Ajoutez un tutoriel interactif à votre projet pour que les utilisateurs soient prêts à se lancer en un rien de temps.

    Le guide qui suit décrit comment créer votre propre tutoriel interactif (comme celui-ci). Il vous accompagne également dans la création d'un bouton que les utilisateurs pourront activer pour démarrer facilement votre tutoriel.

    **Temps nécessaire** : environ 10 minutes

    **Prérequis** : compte GCP

    Cliquez sur le bouton **Continuer** pour passer à l'étape suivante.

  • Page en arrière-plan

    • Plantez le décor : il est souvent utile, lors de la rédaction d'un tutoriel, de le mettre en contexte. Fournissez un aperçu du produit ou présentez rapidement les principales caractéristiques d'une interface utilisateur.
    Exemple

    ## Qu'est-ce que Cloud Shell ?

    Avant de commencer, voici un aperçu de ce que Cloud Shell peut faire.

    Cloud Shell est une machine virtuelle hébergée personnelle qui est livrée avec des outils de développement pour les produits Google Cloud. Cet environnement shell interactif est fourni avec un éditeur de code intégré, un espace de stockage sur disque persistant et une fonctionnalité d'aperçu sur le Web. Pour utiliser uniquement l'accès par ligne de commande, rendez-vous sur [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).

    Vous pouvez diriger les utilisateurs vers Cloud Shell, et leur donner la possibilité de passer en revue un cas d'utilisation et de se familiariser avec les fonctionnalités spécifiques de votre projet afin qu'ils soient rapidement opérationnels.

    Passez à l'étape suivante pour commencer à configurer votre tutoriel.

  • Exemples de base :

    • Hello World : le premier exemple que vous fournissez doit être suffisamment simple pour que l'utilisateur puisse le tester sans que vous ayez à fournir beaucoup d'explications. Prenez pour référence l'exemple Hello World. Utilisez celui-ci comme base pour vous aider à illustrer des concepts dans votre tutoriel.
    Exemple

    ## Tutoriels contextuels

    Ce qui s'affiche devant vous est un tutoriel contextuel.

    Son contenu s'affiche en même temps que l'environnement Cloud Shell. Vous pouvez y effectuer les étapes décrites. Si le tutoriel et l'environnement de développement sont ouverts au même endroit, sur un seul écran, les utilisateurs apprendront à maîtriser votre projet de manière plus directe et intuitive.

    Exécutez maintenant une commande :

    ```bash

    echo "Hello Cloud Shell"

    ```

    ** Conseil** : Cliquez sur le bouton à côté de la zone de code pour copier la commande. Ensuite, collez-la dans le terminal Cloud Shell afin de l'exécuter.

    Vous allez maintenant apprendre à rédiger et à lancer un tutoriel de base.

  • Contenu du tutoriel

    • Utilisez les options de mise en forme avec parcimonie : les options de mise en forme du texte (gras, italique, etc.) peuvent perturber la lecture. Utilisez-les uniquement lorsque cela est nécessaire et à votre avantage (pour les avertissements, les apprentissages clés, etc.).
    • Harmonisez vos choix grammaticaux : utilisez l'impératif pour décrire une action que le participant doit accomplir et assurez-vous de terminer chaque phrase par un point.
    • Faites référence à des liens : lorsque c'est nécessaire, incluez des liens supplémentaires ([texte du lien](URL du lien)) afin que les utilisateurs puissent effectuer leurs propres recherches.
    • Préférez les effets de surbrillance aux captures d'écran : les effets de surbrillance mettent en évidence l'emplacement des éléments de l'interface utilisateur dans la console, de sorte que les participants puissent les identifier directement sans avoir à se référer à une image externe.
    • Proposez un autre format : si possible, fournissez un lien vers votre tutoriel sous forme de contenu statique. Cela donne aux utilisateurs la liberté de choisir comment ils souhaitent visualiser les informations fournies.
    • Donnez des conseils : le cas échéant, ajoutez des conseils (clairement signalés comme suit : "**Conseil :**") pour fournir aux utilisateurs des solutions plus intuitives et leur indiquer les bonnes pratiques.
    Exemple

    ## Écrivez au format Markdown

    Pour écrire votre tutoriel, utilisez [Markdown] (https://fr.wikipedia.org/wiki/Markdown) et suivez les instructions ci-dessous :

    ### Modifiez le titre

    Modifiez le titre de ce tutoriel (''# Introduction à la rédaction de tutoriels dans Cloud Shell") en le remplaçant par :

    ```

    # Apprenez-moi à écrire un tutoriel

    ```

    ### Ajoutez une étape

    Ajoutez ensuite une étape, juste après le titre, comme ceci :

    ```

    ## Étape 1

    Je viens d'ajouter une nouvelle étape.

    ```

    Chaque étape d'un tutoriel s'affiche sur une page distincte.

    **Conseil** : Pour parcourir ces étapes, les utilisateurs cliquent sur les boutons "Précédent" et "Continuer/Suivant".

  • Conclusion

    • Félicitez les participants : veillez à ajouter une icône de trophée (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) pour remercier les utilisateurs d'avoir pris le temps de suivre le tutoriel.
    • Récapitulez le tutoriel : résumez les points importants que les utilisateurs doivent retenir du tutoriel.
    • Indiquez les étapes suivantes : aidez les utilisateurs à aller plus loin en leur proposant des étapes supplémentaires. Il peut s'agit d'une lecture recommandée, de ressources complémentaires, voire d'un autre tutoriel.
    • Accompagnez les utilisateurs jusqu'au bout : conseillez-leur de nettoyer toutes les ressources de test créées dans le cadre du tutoriel, afin d'éviter des frais inutiles.
    Exemple

    ## Félicitations !

    <walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>

    C'est terminé !

    Vous pouvez désormais demander aux participants de lancer votre tutoriel dans Cloud Shell afin d'apprendre à utiliser votre projet.

    Pour obtenir une liste complète des outils de rédaction de tutoriels Cloud Shell, reportez-vous à la section [Documentation de référence sur Markdown pour les tutoriels] (https://cloud.google.com/shell/docs/tutorial-markdown-reference).

    **N'oubliez pas le nettoyage** : Si vous avez créé des projets test, veillez à les supprimer pour éviter des frais inutiles. Utilisez la commande `gcloud projects delete <ID-PROJET>`.

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…