Reglas para escribir tutoriales de software

• La mayoría de los tutoriales de software omiten detalles importantes o incluyen suposiciones ocultas que no coinciden con las expectativas del lector, lo que hace imposible reproducir el proceso
• Siguiendo unas cuantas reglas simples, escribir un tutorial excelente es más fácil de lo que parece

Reglas

1. Escribir para principiantes
2. Crear un título que prometa un resultado claro
3. Explicar el objetivo en la introducción
4. Mostrar el resultado final por adelantado
5. Escribir fragmentos de código que se puedan copiar y pegar
6. Usar flags largas en los comandos
7. Separar los valores personalizados de la lógica reutilizable
8. Reducir el esfuerzo del lector
9. Escribir de forma que el código siempre se mantenga funcionando
10. Enseñar solo un tema
11. Priorizar la claridad sobre los adornos
12. Minimizar las dependencias
13. Especificar claramente los nombres de archivo
14. Usar títulos consistentes y descriptivos
15. Demostrar que la solución funciona
16. Enlazar un ejemplo completo

Escribir para principiantes

• El error más común en los tutoriales es explicar conceptos de nivel principiante con términos de nivel experto. La mayoría de las personas que buscan tutoriales son principiantes.
  • Puede que no sean principiantes en programación, pero sí lo son en el dominio que quieren aprender
• Escribe pensando en principiantes y evita usar terminología de nivel experto
• Evita términos difíciles y usa un lenguaje simple que el lector pueda entender
• Por ejemplo, en un tutorial de React, ofrece una explicación como "crear una página web simple con React" en lugar de "JSX transpilation"

Crear un título que prometa un resultado claro

• El título debe comunicar de forma específica qué podrá aprender el lector con el tutorial
• Evita títulos poco claros o ambiguos y explica con claridad el resultado esperado
  • Ejemplo: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Explicar el objetivo en la introducción

• Cuando el lector hace clic en el tutorial, significa que le interesa lo que dices. Pero aun así debes convencerlo de seguir leyendo
• Hay dos cosas que el lector quiere saber
  • ¿Debería interesarme esta tecnología?
  • Si me interesa, ¿este tutorial es adecuado para mí?
• En la introducción, explica de forma concisa la importancia de la tecnología y la utilidad del tutorial
• Proporciona información útil para despertar el interés del lector y evita descripciones vagas
  • Ejemplo: un tutorial de Docker debe explicar claramente el problema que resuelve Docker y el resultado esperado

Mostrar el resultado final por adelantado

• Tan pronto como sea posible, muestra una demo o captura de pantalla de lo que el lector va a crear con el tutorial
  • Mostrar el resultado final al inicio del tutorial deja claro cuál es la meta
• Ejemplo: incluir una captura del producto final, la UI o un ejemplo de funcionamiento

Escribir fragmentos de código que se puedan copiar y pegar

• Escribe de forma que el lector pueda copiar fácilmente el código, pegarlo en el editor o en la terminal, y ejecutarlo
• Elimina elementos innecesarios como el símbolo de prompt $ en la terminal
• Usa flags no interactivos para simplificar los comandos y && para que el proceso se detenga si algo falla

Usar flags largas en los comandos

• En los comandos, usa flags largas y más descriptivas en lugar de flags cortas, para que incluso los principiantes puedan entenderlas fácilmente
  • -r en lugar de --recursive

Separar los valores personalizados de la lógica reutilizable

• Separa claramente en el código los valores que el usuario debe modificar de aquellos que no debe tocar
• Usa variables de entorno para definir valores personalizados y mejorar la legibilidad del código

Reducir el esfuerzo del lector

• Respeta el tiempo del lector para que la experiencia con el tutorial sea agradable
• Sustituye tareas tediosas por fragmentos de comandos
  • Ejemplo: resolver algo con comandos en lugar de pedir que se edite un archivo manualmente

Escribir de forma que el código siempre se mantenga funcionando

• El código de ejemplo siempre debe poder ejecutarse y mantenerse funcional incluso en los pasos intermedios
• El código incorrecto o los ejemplos que no funcionan causan confusión al lector

Enseñar solo un tema

• El tutorial debe centrarse en un solo tema y no mezclar tecnologías no relacionadas
• Por ejemplo, no agregues tecnologías de AI innecesarias a un tutorial que explica una función de búsqueda

Priorizar la claridad sobre los adornos

• Al lector no le importa si una aplicación de juguete se ve bonita
• Minimiza el CSS o los elementos de diseño innecesarios y enfócate en el concepto central
• Usa código simple en lugar de ejemplos complejos para transmitir con claridad el concepto

Minimizar las dependencias

• Reduce al mínimo las dependencias que el lector debe instalar para mejorar la accesibilidad del tutorial
• Especifica claramente las dependencias obligatorias e indica versiones concretas

Especificar claramente los nombres de archivo

• Indica con precisión al lector qué rutas de archivo y qué contenido debe modificar
• Por ejemplo, en lugar de decir "agrega la configuración al archivo config", proporciona la ruta completa del archivo y código concreto indicando exactamente qué línea editar

Usar títulos consistentes y descriptivos

• Usa encabezados estructurados para que al lector le resulte fácil escanear el tutorial
• Estructura el tutorial con títulos que reflejen una organización lógica
• Mantén consistentes el formato, el enfoque y el tiempo verbal de los títulos

Demostrar que la solución funciona

• Si el tutorial enseña a instalar una herramienta o integrar varios componentes, muestra cómo usar el resultado
  • Muestra visualmente al lector el resultado del funcionamiento de la herramienta instalada o integrada
• Por ejemplo, muestra la página de éxito de nginx y cómo verificarla mediante la URL

Enlazar un ejemplo completo

• Enlaza un repositorio que incluya todo el código del tutorial para que se pueda revisar el flujo completo
• Divide el código de cada paso en ramas de git separadas para que el lector pueda seguir cada etapa

[godogi7]

De referencia

[wedding]

¡Esto merece un ward!

[ilikeall]

Es un buen texto.

[halfenif]

Hace poco seguí el tutorial de dagster. Pensé que estaba muy bien hecho.

https://courses.dagster.io/

[aer0700]

Vi todo el tutorial de Dagster y está muy bueno.
El tutorial de Django tiene buen contenido, pero es demasiado largo, así que a mí no me gusta mucho. Ojalá lo dividieran un poco más.

[savvykang]

También está Django como ejemplo de un tutorial bien hecho: https://docs.djangoproject.com/en/5.1/intro/tutorial01/

[jhj0517]

Usa un lenguaje simple y muestra primero el resultado final.

[aer0700]

A veces hay documentos tutoriales que, en lugar de mostrar el uso básico y aburrido del framework, buscan mostrar qué tan genial es este framework.
Entré a "Get started", pero si lo que está marcado como tutorial de uso básico es un documento de 10 páginas, me desagrada muchísimo.

[beenzinozino]

Todos están impresionantes...

[savvykang]

https://tanstack.com/table/latest/docs/introduction

[nono9633]

https://github.com/tmux/tmux/wiki/Getting-Started