Les consignes suivantes vous aideront à présenter votre contenu sous forme de tutoriel afin que vos utilisateurs puissent 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 situé à droite de la console Google Cloud.
- Navigation : les utilisateurs peuvent parcourir le tutoriel à l'aide des boutons Suivant et Précédent à chaque étape. Ils peuvent également fermer le tutoriel et reprendre là où ils se sont arrêtés.
- Code à parcourir : les extraits de code peuvent être copiés directement dans Cloud Shell.
Session de l'éditeur Cloud Shell avec un volet de tutoriel ouvert. Les utilisateurs peuvent copier le code directement dans Cloud Shell en cliquant sur un bouton, puis en basculant entre les pages avec les boutons Suivant et Précédent.
Style de rédaction
- 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.
| Original | 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 grâce auxquels les utilisateurs pourront lancer 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** : un compte de facturation Cloud
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 vos utilisateurs vers Cloud Shell pour les aider à démarrer rapidement votre projet. Ils auront ainsi la possibilité de parcourir un cas d'utilisation et de se familiariser avec les fonctionnalités de votre projet.
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.
- Choisissez la mise en surbrillance plutôt que les captures d'écran:cette action met en évidence l'emplacement des éléments de l'interface utilisateur dans la console Google Cloud afin que les utilisateurs puissent les identifier sans avoir à rechercher d'image.
- 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 rédiger votre tutoriel, utilisez [Markdown](https://fr.wikipedia.org/wiki/Markdown) et suivez ces consignes:
### 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".
Résumé
- 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 utilisateurs de lancer votre tutoriel dans Cloud Shell et de commencer à utiliser votre projet en toute simplicité.
Pour obtenir la liste complète des outils de rédaction de tutoriels Cloud Shell, consultez la [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>`.