Trata la documentación como parte del cambio
Cuando cambia el comportamiento, el momento más fiable para actualizar la documentación es en la misma pull request. Los revisores pueden comparar implementación y explicación a la vez, y las etiquetas de versión mantienen la documentación alineada con el código publicado.
- Mantén un README enfocado junto al componente que explica.
- Exige actualizaciones de documentación cuando cambien el comportamiento público, la configuración o los pasos operativos.
- Usa comprobaciones de enlaces y estilo en la integración continua.
- Asigna una responsabilidad clara para los runbooks de alto riesgo y las páginas de referencia.
Elige el tipo de documento antes de escribir
Un tutorial enseña mediante una secuencia. Una guía práctica resuelve una tarea. El material de referencia describe el comportamiento exacto. Una explicación aporta contexto y compensaciones. Mezclar los cuatro en un único README largo hace que cada uno sea más difícil de usar.
Los registros de decisiones de arquitectura son otro patrón útil: registra el contexto, la decisión, las alternativas y las consecuencias mientras el razonamiento sigue fresco. Markdown mantiene el registro cerca del código sin requerir un flujo de publicación aparte.
Haz que los ejemplos de código sean comprobables y honestos
Las personas que leen copian los ejemplos. Incluye los imports necesarios, nombres realistas, la salida esperada y la ruta de error correspondiente. Si el fragmento está incompleto a propósito, dilo. Un ejemplo pequeño y probado vale más que un bloque grande que solo parece plausible.
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
Optimiza para obtener diffs fáciles de revisar
Usa una frase por línea solo si el repositorio adopta esa convención de forma coherente; de lo contrario, ajusta el texto de forma natural y deja que las herramientas gestionen la presentación. Evita reformatear un archivo entero durante una edición de contenido. Los encabezados estables y los enlaces de estilo referenciado pueden facilitar los cambios en documentos grandes sin diffs ruidosos.
- Da a los encabezados nombres específicos que sigan siendo útiles en los anclajes generados.
- Mantén tablas estrechas y evita celdas cargadas de prosa.
- Usa enlaces relativos para los archivos que se mueven con el repositorio.
- No pegues secretos, registros privados ni datos de producción sin redactar en los ejemplos.
Usa la conversión como punto de partida de la migración
Un archivo de Word, una hoja de cálculo, un PDF o una presentación pueden contener conocimiento valioso que aún no encaja en un flujo de documentación como código. Convertirlo a Markdown elimina gran parte de la capa de presentación, pero un desarrollador aún necesita normalizar encabezados, reparar enlaces, elegir los límites de los archivos y confirmar la precisión técnica.
Conserva el documento original hasta que se haya revisado la versión convertida. Para datos calculados o registros firmados, el original puede seguir siendo la fuente de verdad incluso después de añadir una instantánea legible en Markdown al repositorio.