Introduction
Un atelier de programmation est un tutoriel interactif écrit en syntaxe markdown. Nous publions nos ateliers de programmation à l'adresse blocklycodelabs.dev. Les ateliers de programmation utilisent à la fois du langage naturel, des exemples de code et des captures d'écran pour créer une expérience de tutoriel plus intéressante. L'utilisateur cible d'un atelier de programmation suit et exécute le code au fur et à mesure qu'il le lit.
Rédiger un atelier de programmation est un excellent moyen de contribuer à la communauté. C'est une façon de partager vos connaissances et de faciliter la vie du prochain développeur qui rencontrera le même problème.
Qu'est-ce qui rend un atelier de programmation efficace ?
Un atelier de programmation efficace doit être ciblé et lisible. Il indique clairement à l'utilisateur ce qu'il va créer et ce qu'il va apprendre, et l'aide à écrire et à comprendre le code pour effectuer une tâche spécifique.
Traiter
Si vous avez une idée pour un atelier de programmation, vous pouvez nous en faire part en effectuant une demande de fonctionnalité dans le dépôt blockly-samples. Décrivez ce que vous voulez enseigner et ce que vous allez créer dans cet atelier de programmation. Nous discuterons de l'idée et l'affinerons. Vous pouvez ensuite le rédiger et envoyer une demande d'extraction pour celle-ci. Une fois qu'elle aura été examinée, un membre de l'équipe Blockly le publiera.
Conseils d'écriture
Le reste de cette page est un ensemble de conseils et de questions pour vous guider dans la rédaction d'un atelier de programmation.
Consultez Technical Écriture One pour une introduction rapide à la rédaction technique.
Audience
- Qui est le lecteur cible ?
- Que sait-il déjà de l'utilisation de Blockly ?
- Qu'essaie-t-il d'apprendre ?
Prérequis
- Quelle est la configuration minimale requise pour que l'utilisateur exécute votre code ?
Si cela est utile, vous pouvez publier le code de démarrage et le code terminé dans le répertoire examples.
Structurer
Comme pour tout texte, commencez par un plan. La structure est adaptée à la plupart des ateliers de programmation:
- Présentation
- Objectifs de l'atelier
- Objectifs de l'atelier
- Ce que vous devez savoir
- Instructions de configuration
- Étape 1: [Insérer le titre]
- Explication/Motivation
- Exemple de code
- Résultats attendus
- (Facultatif) Plus d'explications
- ...
- Étape 10: [Insérer le titre]
- Récapitulatif
- Ce que vous avez appris
- Ce que vous avez créé
- Ressources supplémentaires
- Lien vers le code finalisé (le cas échéant)
Même si vous pouvez avoir plus de 10 étapes, si vous en atteignez 20, vous devriez envisager de la diviser en deux ateliers de programmation.
Style de rédaction
- Utilisez un style d'écriture conversationnel.
- Utilisez des titres pour clarifier l'organisation.
- Utilisez des listes à puces pour diviser les murs de votre texte.
- Utilisez des images et des GIF !
Style du code
- Vous pouvez écrire en ES5, ES6 ou TypeScript, mais indiquez au lecteur de quel élément il s'agit au début.
- Suivez le guide de style Google.