Convertir un documento de Word en un README de GitHub

La documentación a menudo nace en Word: una especificación escrita por producto, las notas de instalación de un cliente, un informe que ahora tiene que vivir junto al código. En GitHub, el sitio natural para ese texto es un archivo README.md, que se muestra en la portada del repositorio. Volver a escribirlo es lento y propenso a errores. Convertirlo lleva un minuto, y unos pocos ajustes hacen que el resultado parezca escrito para GitHub desde el principio.

1. Prepara el documento de Word

El conversor traslada la estructura de Word a Markdown, así que un documento bien estructurado se convierte limpio. Antes de convertir, dedica dos minutos a esto:

• Usa estilos de título (Título 1, Título 2…) en lugar de texto grande en negrita. Se convierten en encabezados # y ##, y GitHub los usa para construir el índice del archivo.
• Usa listas reales (los botones de viñetas y numeración), no guiones escritos a mano.
• Mantén las tablas sencillas. Las tablas Markdown no pueden combinar celdas; una celda combinada conserva su texto en la primera columna.
• Pon texto alternativo a las imágenes (clic derecho → Editar texto alternativo). Se convierte en la descripción de la imagen en Markdown.

2. Convierte a Markdown

Abre el conversor de Word a Markdown y suelta tu .docx (los .doc antiguos también funcionan). El archivo se convierte en tu navegador y no se sube nada, algo útil con documentos internos.

Si el documento tiene imágenes, activa Incluir imágenes antes de convertir y usa Descargar .zip. El zip contiene el archivo Markdown y una carpeta images/, y el Markdown ya apunta a images/image-1.png, etc. Sin esa opción, cada imagen se sustituye por su texto alternativo.

Renombra el archivo Markdown a README.md y colócalo, junto con la carpeta images/, en la raíz del repositorio. GitHub resuelve las rutas relativas de las imágenes, así que se verán en la página del repositorio.

3. Pule el texto para GitHub

La conversión conserva el texto, los títulos, el énfasis, las listas, las tablas, los enlaces y las notas al pie. Lo que no puede adivinar es la intención: Word no tiene el concepto de bloque de código, y un texto pensado para imprimir no siempre encaja en un README. Repasa estos puntos:

• Un solo título. Deja un único encabezado # con el nombre del proyecto arriba y convierte todo lo demás en ## o inferior.
• Bloques de código. Rodea comandos y ejemplos con bloques delimitados indicando el lenguaje, para que GitHub los resalte:

  ```bash
  npm install
  npm run dev
  ```

• Comillas rectas en el código. Word sustituye " y ' por comillas tipográficas (“ ” ‘ ’) y los guiones por rayas. Dentro de comandos y código rompen el copiar y pegar, así que cámbialas.
• Código en línea para nombres de archivo, comandos y opciones: `config.yml`, `--verbose`.
• Enlaces relativos. Apunta a otros archivos del repositorio con rutas como [Cómo contribuir](CONTRIBUTING.md) en lugar de URLs absolutas, para que los enlaces sigan funcionando en forks y ramas.
• Sin índice manual. GitHub añade un menú de esquema a cada archivo Markdown generado a partir de los títulos. Un índice numerado copiado de Word se quedará desfasado; elimínalo.
• Diagramas y fórmulas. GitHub muestra los bloques mermaid como diagramas y el LaTeX entre signos $ como fórmulas, así que puedes cambiar las capturas de diagramas de flujo sencillos por un bloque Mermaid más fácil de mantener.

Una estructura de README que funciona

Si el documento original no se escribió como README, reorganízalo en torno a lo que un visitante necesita primero:

1. Nombre del proyecto y una descripción de una frase.
2. Una captura o un ejemplo breve, si ayuda.
3. Instalación y primeros pasos.
4. Uso y configuración.
5. Cómo contribuir, licencia y contacto.

Las especificaciones largas pueden ir a una carpeta docs/ enlazada desde el README.

4. Revisa y haz commit

Pega el README en el editor de Markdown para revisar títulos, tablas y bloques de código en la vista previa. Las imágenes de la carpeta images/ no se verán ahí, porque una página web no puede leer archivos de tu disco, pero sí en GitHub. Cuando esté bien:

git add README.md images/
git commit -m "Añadir README"
git push

Extra: el mismo Markdown sirve en sentido contrario. Desde el editor, Descargar PDF te da un PDF cuidado del README para quien prefiera un documento a un repositorio. La guía de Markdown recoge todos los elementos que admite el editor.