Introduction
Un atelier de programmation est un tutoriel interactif écrit en syntaxe Markdown. Nous publions nos ateliers de programmation sur blocklycodelabs.dev. Ils utilisent un mélange de langage naturel, d'exemples de code et de captures d'écran pour créer une expérience de tutoriel plus intéressante. L'utilisateur cible d'un atelier de programmation suit les instructions et exécute le code au fur et à mesure de sa lecture.
Écrire un atelier de programmation est un excellent moyen de contribuer à la communauté. C'est un moyen de partager vos connaissances et de faciliter la vie du prochain développeur qui rencontrera le même problème.
Qu'est-ce qui fait un bon atelier de programmation ?
Un atelier de programmation réussi est ciblé et lisible. Il indique clairement à l'utilisateur ce qu'il va créer et apprendre, et le guide dans l'écriture et la compréhension du code pour accomplir une tâche spécifique.
Processus
Si vous avez une idée d'atelier de programmation, vous pouvez nous en faire part en envoyant une demande de fonctionnalité dans le dépôt blockly-samples. Incluez une description de ce que vous souhaitez enseigner et de ce que vous allez créer dans l'atelier de programmation. Nous discuterons de l'idée et la préciserons. Vous pouvez ensuite le rédiger et envoyer une demande d'extraction. Une fois qu'il a été examiné, un membre de l'équipe Blockly le publiera.
Conseils d'écriture
Le reste de cette page contient un ensemble de conseils et de questions pour vous guider dans la rédaction d'un atelier de programmation.
Consultez Technical Writing One pour une brève présentation de la rédaction technique.
Audience
- À qui s'adresse le contenu ?
- Que sait-elle déjà sur l'utilisation de Blockly ?
- Qu'essaient-ils d'apprendre ?
Configuration
- Quelle est la configuration minimale requise pour que l'utilisateur puisse exécuter votre code ?
Si cela peut vous aider, vous pouvez publier le code de démarrage et le code terminé dans le répertoire examples.
Structure
Comme pour tout texte, commencez par un plan. Voici une structure adaptée à la plupart des ateliers de programmation :
- Introduction
- Points abordés
- Ce que vous allez faire
- Ce que vous devez savoir
- Instructions de configuration
- Étape 1 : [Title goes here]
- Explication/Motivation
- Exemple de code
- Résultats attendus
- (Facultatif) Plus d'explications
- …
- Étape 10 : [Titre]
- Résumé
- Ce que vous avez appris
- Ce que vous avez créé
- Ressources supplémentaires
- Lien vers le code complet (le cas échéant)
Vous pouvez avoir plus de dix étapes, mais si vous en avez vingt, vous devriez envisager de les diviser en deux ateliers de programmation.
Style de rédaction
- Utilisez un style d'écriture conversationnel.
- Utilisez des titres pour rendre l'organisation claire.
- Utilisez des listes à puces pour éviter les blocs de texte.
- Utilisez des images et des GIF.
Style de code
- Vous pouvez écrire en ES5, ES6 ou TypeScript, mais indiquez au lecteur de quel langage il s'agit au début.
- Suivez le guide de style Google.