Guide de rédaction

Afin que les utilisateurs puissent se familiariser efficacement avec votre projet, voici quelques conseils pour mieux présenter votre contenu sous forme de tutoriel.

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 se déplacer dans le tutoriel à l'aide des boutons "Continuer" et "Retour". 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 le choix de quitter le tutoriel avec Annuler le tutoriel et peuvent ensuite reprendre là où ils se sont arrêtés.
  • Code à parcourir : vous pouvez inclure des extraits de code dans votre tutoriel. Ceux-ci seront mis en forme avec l'icône en ligne Icône de copie, qui permet aux utilisateurs d'effectuer facilement un copier-coller directement dans Cloud Shell.

Session de console avec un tutoriel lancé

Session de console avec panneau Tutoriel ouvert sur le côté droit. Les utilisateurs peuvent copier le code directement dans Cloud Shell à l'aide de l'icône en ligne et peuvent se déplacer entre les pages en utilisant Retour et Continuer.

Style d'écriture

  • Restez léger : les tutoriels doivent être informatifs et utiles, mais pas trop formels dans le ton.
  • 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.
  • Ayez des objectifs ciblés : avant d'écrire le contenu de votre tutoriel, définissez un objectif bien défini que vous souhaitez que vos utilisateurs atteignent. Créez votre tutoriel en gardant cet objectif à l'esprit.
Original Version corrigée Amélioration
Sur la page suivante, vous apprendrez à créer 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 explique également comment générer un bouton permettant aux utilisateurs de lancer le tutoriel quand vous l'aurez terminé.

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

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

Bonnes pratiques

  • Soyez bref : les contraintes d'espace uniques du panneau Tutoriel signifient qu'une quantité limitée d'informations peut être présentée à un utilisateur à 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 vos attentes : expliquez brièvement comment vos utilisateurs tireront profit de ce tutoriel.
    • Indiquez la durée estimée : estimez approximativement le temps requis pour terminer le tutoriel. Essayez de créer un tutoriel pouvant être terminé en moins de 15 minutes. Si votre tutoriel est plus long (ou se compose de plus de 15 pages à forte densité de mots), envisagez de le diviser en une série de tutoriels plus courts.
    • Soyez franc : indiquez clairement les ressources ou les accès prérequis que les utilisateurs peuvent avoir besoin de configurer pour fonctionner sans interruption dans le tutoriel.
    Exemple

    ## C'est parti !

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

    Ce guide vous explique comment créer votre propre tutoriel interactif (comme celui-ci). Il vous expliquera également comment générer un bouton qui permet aux utilisateurs de lancer le tutoriel quand vous l'aurez terminé.

    **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 cet exemple comme base à étoffer pour illustrer les concepts tout au long du tutoriel.
    Exemple

    ## Tutoriels contextuels

    Ce que vous regardez maintenant est un tutoriel en contexte.

    Le contenu est affiché avec l'environnement Cloud Shell où vous pouvez effectuer les étapes du tutoriel. Ouvrir le tutoriel et l'environnement de développement au même endroit permet à vos utilisateurs de commencer à utiliser votre projet plus facilement grâce à une expérience simple à un seul écran.

    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.

    Ensuite, vous allez écrire 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.
    • Autre vue : si possible, fournissez un lien vers le contenu de votre tutoriel en tant que contenu statique ; cela donne aux utilisateurs la liberté de choisir comment ils souhaitent consommer 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 rédiger votre tutoriel, utilisez [Markdown](https://en.wikipedia.org/wiki/Markdown) et suivez ces instructions :

    ### Modifiez le titre

    Modifiez le titre de ce tutoriel ('# Introduction à l'écriture de tutoriels dans Cloud Shell') en le changeant en :

    ```

    # 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".

  • Résumé

    • Félicitations : assurez-vous d'ajouter une icône de trophée (<walkthrough-conclusion-trophy> </walkthrough-conclusion-trophy>) pour féliciter les utilisateurs d'avoir pris le temps de terminer le tutoriel.
    • Récapitulatif : résumez les leçons importantes que vous souhaitez que les utilisateurs retiennent 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 maintenant demander aux utilisateurs de lancer votre tutoriel dans Cloud Shell et les faire commencer à utiliser votre projet en toute simplicité.

    Pour une liste complète des outils d'écriture de tutoriel de Cloud Shell, reportez-vous à la [Documentation de référence sur Markdown pour les tutoriels](https://cloud.google.com/shell/docs/walkthrough-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>`.