Todo el mundo ha abandonado un tutorial en el paso 4. Seguiste todo al pie de la letra, pero el comando no funciona, la pantalla no coincide con la captura y cierras la pestaña. Casi nunca es culpa tuya: es de quien lo escribió. Se puede hacer de otra manera, y no es difícil.
Antes de escribir, responde dos preguntas
¿Para quién es esto y qué podrá hacer esa persona después? Si no respondes las dos en una frase, el tutorial se desviará. «Para un dev júnior que nunca ha levantado un container y que, al final, tendrá la app funcionando en localhost:3000». Listo. Ahora sabes qué recortar y dónde detenerte.
Un solo camino, y que funcione
Un tutorial no es documentación de referencia. Elige UN camino, el más directo, e ignora los desvíos. Nada de «si usas macOS, haz X; si usas Windows, Y; si prefieres yarn...». Cada bifurcación duplica las posibilidades de que la persona se pierda. Las variantes pueden convertirse en notas al pie o en otro artículo.
Muestra adónde llegará la persona
Al principio, muestra el resultado. Una captura de la pantalla final, el JSON de respuesta o el sitio funcionando. Eso aporta contexto y motiva: la persona sabe que el esfuerzo tiene un destino. Sin esto, cada paso es un salto a oscuras.
Un comando que se pueda copiar sin pensar
Un buen comando es uno que la persona pega y ejecuta. Nada de docker run <tu-imagen> con un placeholder que nadie sabe cómo completar. Proporciona el comando completo:
bash docker run -d -p 3000:3000 --name mi-app node:20
Usa bloques de código, un comando por bloque cuando tenga sentido, y muestra la salida esperada justo debajo. Si la persona no ve el mismo output, sabrá de inmediato que algo se desvió del camino.
Equivócate en lugar del lector
Ya sabes dónde tropiezan las personas: un puerto ocupado, permisos insuficientes o una variable de entorno olvidada. Anticípate. Después del paso arriesgado, incluye un bloque breve: «Si aparece EADDRINUSE, el puerto 3000 ya está en uso; cámbialo por el 3001». Eso evita que la persona tenga que abrir tres pestañas de Stack Overflow y abandone a mitad de camino.
La prueba final: hazlo tú mismo desde cero
El tutorial solo está listo cuando lo sigues en una máquina limpia, sin saltarte nada y sin usar lo que ya está instalado en la tuya. Un container nuevo, una carpeta nueva, copiando y pegando cada comando como si fuera la primera vez. Es aquí donde aparecen los pasos que te parecían obvios y que nadie más considera obvios.
Un buen tutorial no es el más completo. Es el que la persona termina. Escribe para llegar hasta el final.
