49. Buenas prácticas {#49-buenas-prácticas}

No existe una única forma correcta de escribir Markdown, pero sí un conjunto de prácticas que mejoran la legibilidad, la portabilidad, el mantenimiento y la accesibilidad. La regla general es: el contenido primero, la herramienta después.

49.1 Estructura y organización {#491-estructura-y-organización}

1. Usa un solo H1 por documento y encabezados jerárquicos.
2. Divide documentos largos en archivos con un propósito claro.
3. Mantén una estructura consistente en todos los documentos.
4. Incluye un índice en documentos extensos.
5. Usa nombres descriptivos para archivos y carpetas (guia-instalacion.md, no doc2.md).
6. Enlaza documentos relacionados con rutas relativas.
7. Mantén el README actualizado y con enlaces a la documentación completa.
8. Versiona la documentación junto al código.
9. Archiva o marca como obsoleta la documentación que ya no aplica.

49.2 Escritura y estilo {#492-escritura-y-estilo}

1. Escribe para el lector: explica el qué, el porqué y el cómo.
2. Usa ejemplos reales y verificables.
3. Sé conciso, pero no omitas información necesaria.
4. Define siglas la primera vez que aparecen.
5. Mantén una terminología consistente.
6. Revisa ortografía y gramática.
7. Evita dobles negaciones y frases ambiguas.
8. Usa voz activa cuando sea posible.
9. Incluye advertencias y requisitos previos antes de los pasos peligrosos.

49.3 Sintaxis y formato {#493-sintaxis-y-formato}

1. Deja una línea en blanco antes y después de títulos, listas, tablas, citas y bloques de código.
2. No uses HTML innecesario; si lo necesitas, justifícalo.
3. Especifica el lenguaje en los bloques de código.
4. Usa tablas con encabezado y columnas claras.
5. Evita líneas excesivamente largas si el proyecto tiene una regla de estilo.
6. Escapa los caracteres especiales cuando deban mostrarse literalmente.
7. Usa listas de tareas solo cuando aporten seguimiento real.
8. No abuses de negritas y mayúsculas para enfatizar.
9. Mantén las tablas simples; si son muy complejas, divide o usa otro formato.
10. Usa bloques de código con fences, no indentación, salvo que el renderizador lo requiera.

49.4 Enlaces, imágenes y multimedia {#494-enlaces-imágenes-y-multimedia}

1. Usa enlaces descriptivos, no “haz clic aquí”.
2. Comprueba los enlaces de forma automática.
3. Usa rutas relativas dentro del repositorio.
4. Incluye texto alternativo en todas las imágenes informativas.
5. Optimiza las imágenes y usa formatos adecuados.
6. Evita imágenes de texto.
7. Añade pies de figura cuando aporten contexto.
8. Incluye subtítulos y transcripciones para vídeo y audio.
9. No enlaces a recursos que puedan desaparecer sin indicar una alternativa.

49.5 Código y ejemplos {#495-código-y-ejemplos}

1. Muestra código completo y ejecutable cuando sea posible.
2. Indica el lenguaje y la versión si afecta al ejemplo.
3. Evita secretos, tokens y datos personales en los ejemplos.
4. Marca las líneas que cambian con comentarios, no solo con color.
5. Explica el resultado esperado después del ejemplo.
6. Mantén los ejemplos sincronizados con el código real; si es posible, genéralos o pruébalos en CI.

49.6 Documentación de proyectos {#496-documentación-de-proyectos}

1. README claro con descripción, instalación, uso, requisitos y licencia.
2. CONTRIBUTING.md con el flujo de contribución.
3. CHANGELOG.md siguiendo Keep a Changelog y SemVer cuando aplique.
4. LICENSE explícita.
5. ADR para decisiones arquitectónicas importantes.
6. Documentación de API con endpoints, parámetros, errores y ejemplos.
7. Plantillas para issues, pull requests y documentos repetidos.
8. Guía de estilo para el equipo.
9. Fecha de última revisión o versión en documentos críticos.

49.7 Calidad automatizada {#497-calidad-automatizada}

1. Linting en local y en CI.
2. Formateo consistente con Prettier u otra herramienta.
3. Comprobación de enlaces.
4. Corrección ortográfica.
5. Validación de Front Matter.
6. Compilación de MDX y Mermaid en CI.
7. Previsualización del sitio antes de publicar.
8. Revisión por pares de los cambios de documentación.

49.8 Seguridad y accesibilidad {#498-seguridad-y-accesibilidad}

1. Sanitiza el HTML si el contenido no es de confianza.
2. No compiles MDX no confiable.
3. Revisa dependencias y plugins.
4. Aplica accesibilidad desde el principio, no como una corrección final.
5. Prueba con teclado y lector de pantalla.
6. Mantén el contraste y no dependas solo del color.
7. Usa lenguaje claro y estructura predecible.

49.9 Checklist final {#499-checklist-final}

• Título y jerarquía correctos.
• Introducción y propósito claros.
• Ejemplos verificados.
• Enlaces y anclas funcionales.
• Imágenes con alt.
• Tablas con encabezado.
• Código con lenguaje.
• Sin HTML innecesario.
• Sin secretos ni datos personales.
• Linting y enlaces comprobados.
• Documento revisado por otra persona.
• Publicado en el formato correcto.