Introducción
Un codelab es un instructivo interactivo escrito en sintaxis 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 el código y lo ejecuta a medida que lo lee.
Escribir un codelab es una excelente manera de contribuir a la comunidad. Es una forma de compartir tu conocimiento y facilitarle la vida al 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 compilará y lo que 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. Para ello, envía una solicitud de función en el repositorio de blockly-samples. Incluye una descripción de lo que quieres enseñar y lo que compilarás en el codelab. Analizaremos y definiremos mejor la idea. Luego, puedes escribirlo y enviar una solicitud de extracción para él. Una vez que se revise, un miembro del equipo de Blockly la publicará.
Consejos de escritura
El resto de esta página es un conjunto de sugerencias y preguntas para guiarte a la hora de escribir 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é intenta aprender?
Configuración
- ¿Cuál es la configuración mínima requerida para que el usuario ejecute tu código?
Si te resulta útil, puedes publicar el código de partida y el código completo en el directorio examples.
Estructura
Como con cualquier escrito, comienza con un esquema. Esta es una buena estructura para la mayoría de los codelabs:
- Introducción
- Qué aprenderás
- Qué compilarás
- Qué debes saber
- Instrucciones de configuración
- Paso uno: [Title goes here]
- Explicación/motivación
- Muestra de código
- Resultados esperados
- Más explicaciones (opcional)
- …
- Paso diez: [Title goes here]
- Resumen
- Qué aprendiste
- Qué compilaste
- Recursos adicionales
- Vínculo al código completo (si está disponible)
Si bien puedes tener más de diez pasos, si llegas a veinte, considera dividirlo en dos codelabs.
Estilo de escritura
- Usa un estilo de escritura informal.
- Usa encabezados para que la organización sea clara.
- Usa listas con viñetas para dividir los textos largos.
- Usa imágenes y GIFs.
Estilo de código
- Puedes escribir en ES5, ES6 o TypeScript, pero debes indicarle al lector cuál es al comienzo.
- Sigue la guía de estilo de Google.