Introduction
Un atelier de programmation est un tutoriel interactif rédigé en syntaxe Markdown. Nous publions nos ateliers de programmation sur blocklycodelabs.dev. Ils combinent le 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 de sa lecture.
Créer 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 ce qu'il va 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 en discuterons et l'affinerons. Vous pouvez ensuite rédiger la modification et envoyer une demande d'extraction. Une fois l'examen terminé, un membre de l'équipe Blockly la 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 Writing One pour une introduction rapide à la rédaction technique.
Audience
- Qui est le lecteur cible ?
- Que sait-il déjà sur l'utilisation de Blockly ?
- Que cherche-t-il à 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 finalisé dans le répertoire examples.
Structure
Comme pour tout texte, commencez par un plan. Il s'agit d'une bonne structure pour 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: [Titre ici]
- Explication/Motivation
- Exemple de code
- Résultats attendus
- (Facultatif) Explication supplémentaire
- …
- Étape 10: [Title goes here]
- Résumé
- Ce que vous avez appris
- Ce que vous avez créé
- Ressources supplémentaires
- Lien vers le code finalisé (le cas échéant)
Vous pouvez avoir plus de 10 étapes, mais si vous atteignez 20 étapes, envisagez de les 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 longs textes.
- 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.