Introducción
Un codelab es un instructivo interactivo escrito con 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 el proceso y lo ejecuta a medida que lee.
Escribir un codelab es una excelente manera de contribuir a la comunidad. Es una forma de compartir tus conocimientos y facilitarle la vida al próximo desarrollador que tenga el mismo problema.
¿Qué hace que un codelab sea excelente?
Un buen codelab es enfocado y legible. Le dice claramente al usuario lo que compilará y lo que aprenderá, y lo guía a través de la escritura y la comprensión del código para completar una tarea específica.
Proceso
Si tienes una idea para un codelab, puedes informarnos al respecto mediante una solicitud de función en el repositorio de muestras de bloques. Incluye una descripción de lo que quieres enseñar y lo que compilarás en el codelab. Analizaremos la idea y la definiremos mejor. Luego, puedes escribirlo y enviar una solicitud de extracción para ello. Una vez que haya pasado la revisión, un miembro del equipo de Blockly lo publicará.
Consejos de escritura
El resto de esta página es un conjunto de sugerencias y preguntas que te guiarán en la redacción de un codelab.
Consulta Technical Write One para obtener una introducción rápida a la redacción técnica.
Público
- ¿Quién es el lector objetivo?
- ¿Qué saben ya sobre el uso de Blockly?
- ¿Qué intentan aprender?
Configuración
- ¿Cuál es la configuración mínima que se requiere para que el usuario ejecute tu código?
Si te resulta útil, puedes publicar el código de partida y el código completado en el directorio examples.
Estructura
Al igual que 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
- Qué debe saber
- Instrucciones para la configuración
- Paso uno: [El título va aquí]
- Explicación/motivación
- Muestra de código
- Resultados esperados
- Más explicaciones (opcional)
- ...
- Paso diez: [El título va aquí]
- 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, deberías considerar dividirlo en dos codelabs.
Estilo de escritura
- Usar un estilo de escritura conversacional
- Usa encabezados para que la organización sea clara.
- Usa listas con viñetas para romper muros de texto.
- Usa imágenes y GIFs.
Estilo de código
- Puedes escribir en ES5, ES6 o TypeScript, pero decirle al lector cuál es al principio.
- Sigue la guía de estilo de Google.