Introducción
Un codelab es un instructivo interactivo escrito en sintaxis de Markdown. Publicamos nuestros codelabs en blocklycodelabs.dev. Los codelabs usan una combinación de lenguaje natural, muestras de código y capturas de pantalla para crear una experiencia de instructivo más interesante. El usuario objetivo de un codelab sigue las instrucciones y ejecuta el código a medida que lee.
Escribir un codelab es una excelente manera de contribuir a la comunidad. Es una forma de compartir tus conocimientos y facilitar la vida del próximo desarrollador que se encuentre con el mismo problema.
¿Qué hace que un codelab sea excelente?
Un buen codelab es enfocado y legible. Le indica claramente al usuario lo que creará y aprenderá, y lo guía para escribir y comprender el código para completar una tarea específica.
Proceso
Si tienes una idea para un codelab, puedes contarnos sobre ella haciendo una solicitud de función en el repositorio de blockly-samples. Incluye una descripción de lo que quieres enseñar y lo que crearás en el codelab. Analizaremos y definiremos mejor la idea. Luego, puedes escribirlo y enviar una solicitud de extracción para ello. Una vez que se haya completado la revisión, un miembro del equipo de Blockly la publicará.
Consejos de escritura
El resto de esta página contiene un conjunto de sugerencias y preguntas para guiarte en la escritura de un codelab.
Consulta Technical Writing One para obtener una introducción rápida a la redacción técnica.
Público
- ¿Quién es el lector objetivo?
- ¿Qué saben sobre el uso de Blockly?
- ¿Qué intentan aprender?
Configuración
- ¿Cuál es la configuración mínima que necesita el usuario para ejecutar tu código?
Si es útil, puedes publicar código de partida y código completo en el directorio examples.
Estructura
Como con cualquier texto, comienza con un esquema. Esta es una buena estructura para la mayoría de los codelabs:
- Introducción
- Qué aprenderás
- Qué compilarás
- Lo que debes saber
- Instrucciones de configuración
- Paso uno: [El título va aquí]
- Explicación o motivación
- Muestra de código
- Resultados esperados
- (Opcional) Más explicación
- …
- Paso diez: [El título va aquí]
- Resumen
- Qué aprendiste
- Qué compilaste
- Recursos adicionales
- Vínculo al código completado (si está disponible)
Si bien puedes tener más de diez pasos, si llegas a veinte, deberías considerar dividirlo en dos codelabs.
Estilo de escritura
- Usa un estilo de escritura conversacional.
- Usa encabezados para que la organización sea clara.
- Usa listas con viñetas para dividir los bloques de texto.
- Usa imágenes y GIFs.
Estilo de código
- Puedes escribir en ES5, ES6 o TypeScript, pero indícale al lector cuál es al principio.
- Sigue la guía de estilo de Google