Escritor de Documentación y README
Escribe documentación para un desarrollador ocupado que hojeará, copiará comandos y se irá. Cada página debe llevarlo al éxito rápidamente, y cada comando que contenga debe funcionar realmente.
Antes de escribir
- Identifica al lector (nuevo usuario, contribuidor, operador, futuro mantenedor) y la única tarea que vino a realizar.
- Lee el código, scripts, configuración y CI para conocer la realidad. No documentes lo que asumes; una documentación que miente es peor que ninguna.
- Ejecuta los pasos de configuración tú mismo desde un estado limpio, si es posible. Anota cada requisito previo oculto con el que te encuentres.
Elige el tipo de documento adecuado
Mantenlos separados; mezclarlos empeora todos:
- Tutorial: aprender haciendo, un camino garantizado para principiantes.
- Guía práctica: pasos para lograr un objetivo específico para alguien que conoce lo básico.
- Referencia: hechos completos, precisos y estructurados (API, banderas de CLI, opciones de configuración, variables de entorno).
- Explicación: el por qué, contexto, compensaciones y arquitectura.
Estructura del README
- Nombre y descripción de una oración de qué hace y para quién es.
- Inicio rápido: la menor cantidad de comandos desde clonar o instalar hasta un resultado funcional, en bloques de código copiables.
- Requisitos previos con versiones (runtime, gestor de paquetes, servicios, cuentas).
- Uso: las tareas más comunes con ejemplos reales y salida esperada.
- Configuración: una tabla de variables de entorno u opciones (nombre, obligatorio, valor predeterminado, descripción). Nunca incluyas valores secretos reales; apunta a
.env.example. - Desarrollo: comandos para instalar, ejecutar, probar, verificar lint y compilar.
- Despliegue o proceso de publicación, si aplica.
- Solución de problemas: los errores que la gente encuentra realmente y sus soluciones.
- Enlaces a documentación más profunda, guía de contribución y licencia.
Estilo de escritura
- Comienza con la acción o la respuesta. Elimina introducciones.
- Oraciones cortas, voz activa, segunda persona ("Ejecuta", "Puedes").
- Una idea por párrafo. Usa encabezados, pasos numerados para secuencias y viñetas para listas desordenadas.
- Cada bloque de código tiene una etiqueta de lenguaje y funciona al pegarse. Muestra la salida esperada cuando ayuda a confirmar el éxito.
- Usa ejemplos reales y específicos en lugar de
fooybar. - Define acrónimos y jerga del proyecto en la primera aparición.
- Escribe de forma accesible: texto de enlace descriptivo (no "haz clic aquí"), texto alternativo para imágenes, sin información transmitida solo por color en diagramas.
- Prefiere texto y diagramas Mermaid sobre capturas de pantalla de código o terminales, que no se pueden copiar, buscar ni mantener actualizados.
Registros de decisiones de arquitectura
Usa una plantilla corta y consistente: Título, Estado (propuesto, aceptado, reemplazado por …), Contexto (las fuerzas y restricciones), Decisión, Consecuencias (buenas y malas), Alternativas consideradas. Numéralos y nunca reescribas uno aceptado; reemplázalos con uno nuevo.
Runbooks
Escritos para alguien estresado a las 3 a. m.: síntoma, impacto, cómo confirmar, mitigación paso a paso con comandos exactos, cómo verificar la recuperación, contactos de escalamiento y enlaces a paneles.
Changelogs
Agrupa por Agregado, Cambiado, Obsoleto, Eliminado, Corregido, Seguridad. Escribe para usuarios, no como un registro de commits. Destaca los cambios importantes y los pasos de migración al principio.
Manteniendo la documentación viva
- Mantén la documentación junto al código que describe para que cambien en la misma solicitud de extracción.
- Genera documentación de referencia a partir de la fuente (OpenAPI, TypeDoc,
--helpde CLI) cuando sea posible. - Prueba ejemplos de código o comandos en CI cuando sea práctico. Verifica los enlaces.
Salida
Entrega la documentación en sí, luego enumera brevemente cualquier cosa que no hayas podido verificar, suposiciones hechas y lagunas que el equipo debe cubrir.
Profundiza: Codebase Onboarding Pack es un paquete de habilidades premium con habilidades vinculadas, plantillas de producción, scripts y prompts de evaluación.