Le but de cette partie est de présenter deux éléments :
1/Une brève présentation de ce qui va être présenté dans le tutoriel
2/ Les différentes notions techniques abordées
3/ Les prérequis matériels ou softwares
Il convient ensuite de donner au participants les ressources nécessaires afin qu’il puisse effectuer le tutoriel sans avoir à aller chercher d’eux-mêmes. Il convient de bien préciser les versions utilisées, et de rediriger vers le Github du projet pour éviter toute confusion.
Il y a du sample code à donner ? C’est ici
Il faut installer des éléments ? On donne les liens pour qu’ils n’aient plus qu’à cliquer.
Il y a des petites subtilités de configuration ? On les donne
En bref il faut que le participant ait tout de prêt à la fin de cette partie.
On peut maintenant s’attaquer au vrai tutoriel et rentrer dans le vif du sujet.
Il est important de découper intelligemment les étapes.
Une étape doit faire le focus sur un élément spécifique et être considérée un peu comme une marche d’escalier. La fin d’une étape doit être une avancée significative, mais aussi une possibilité de s’arrêter, et revenir facilement vers ce qui a déjà été fait.
Chaque étape doit disposer d’un moyen de tester si le résultat est correct avant d’avancer à la suivante. Elle doit aussi mettre en garde si des erreurs fréquentes peuvent constituer des pièges.
Une fois le parcours du tutoriel complété, il s’agit maintenant d’accompagner le lecteur dans la vérification de son travail.
En lui donnant les moyens d’observer le résultat de ses actions, en attirant son attention vers certains points critiques où des erreurs sont faciles, à tester sa création...
1/ Ici, on commence par féliciter le courageux qui a su aller au bout du tutoriel.
2/ Ensuite, on lui fait un petit récap’ de tout le travail accompli, de ce qu’il est maintenant capable de mettre en place.
3/ On peut même lui donner quelques exercices à faire, qui allongeront la durée de vie du tutoriel.
4/ Pour finir, on lui met à disposition des ressources supplémentaires, si il veut continuer à creuser par lui-même.
CodeLabs s'installe comme un projet classique.
1 - Cloner le projet
git clone git@github.com:eleven-labs/codelabs.git2 - En local
yarn install
yarn start3 - Via docker
docker-compose up -dAjoutez dans votre /etc/hosts
127.0.0.1 codelabs.localGo to http://codelabs.local
Suivez la procédure sur le repo du blog Eleven-Labs ici
1 - Ajoutez votre tuto
Dans le dossier _posts/codelabs ajoutez un dossier pour votre codelabs avec le naming suivant :
AAAA-MM-DD-titrePuis créez l'architecture suivante :
├── index.json
├── index.md
├── step1.md
├── step2.md
├── step3.md
2 - index.json
C'est le fichier qui permet de configurer votre codelabs. Il doit absolument comporter les informations suivantes :
{
"title": "TITRE",
"permalink": "URL",
"excerpt": "DESCRIPTION",
"slug": "DIRECTORY_NAME_WITHOUT_DATE",
"stepTitles": [
"TITRE STEP 1",
"TITRE STEP 2",
"TITRE STEP 3"
],
"date": "YYYY-MM-DD",
"authors": [
{
"name": "NOM DE L'AUTHOR",
"username": "LOGIN"
}
]
}3 - index.md
Il s'agit du fichier de description du tutoriel. Cette étape permet d'expliquer ce que la personne va apprendre et ce qu'il a besoin d'installer avant de commencer le tutoriel.
Il s'agit d'un fichier en markdown.
4 - step.md
Le découpage du codelabs se fait par étape, il faut alors créer un fichier markdown par étape.
Votre codelabs doit être écrit en markdown. Il existe de nombreuses solutions online pour écrire en markdown comme par exemple :
Si vous avez besoin de mettre des images dans votre article il faut d'abord les ajouter dans le dossier suivant _posts/assets/AAAA-MM-DD-titre/, puis les insérer dans votre article.
en utilsant l'url suivantes https://storage.googleapis.com/tutos/assets/AAAA-MM-DD-titre
5 - Publication
Il vous suffit de faire une pull request avec le nom de branche suivant :
git checkout -b feat/add-codelabs-TITREN'oubliez pas le tag publication.
1 - Validation d'un CodeLabs
Tout le monde peut commenter une pull request de publication. Une fois approuvée, elle est mergée dans master.
ATTENTION: Seulement quelques personnes ont le droit de merger les pulls requests
2 - On partage
Le CodeLabs est en ligne !!! Vous n'avez plus qu'à le partager.
1 - Attention à la taille des images
Ne mettez pas d'image ayant une résolution trop grande sur vos articles. Cela engendrerait des baisses de performance. Il ne sert à rien que votre image fasse plus de 800px de large.
2 - Optimiser vos images
Toujours afin de garder des performances satisfaisantes, optimisez vos images à l'aide de logiciels adaptés. Des logiciels comme ImageOptim sur Mac, Trimage sur Linux ou FileOptimizer sur Windows offrent des interfaces très faciles d'utilisation et des compressions efficaces.