Mejores practicas para usar acs2md en tus proyectos

acs2md funciona mejor cuando los equipos lo tratan como un sistema operativo de exportacion y no como un comando aislado. La documentacion lo refuerza varias veces: valida la maquina, descubre el objetivo, elige el modo correcto y guarda evidencia util cuando algo falle.

Eso es lo que hace que una exportacion masiva sea aburrida en el mejor sentido.

1. Ejecuta doctor cada vez que cambie el entorno

La documentacion de utilidades recomienda doctor despues de activar licencia, despues de cambiar credenciales, antes de la primera exportacion masiva y antes de ejecuciones programadas o de cara al cliente.

Ese deberia ser el baseline:

acs2md doctor

Comprueba:

• validez del archivo de configuracion
• credenciales de Confluence
• conectividad real con la API
• presencia y validez de la licencia
• identidad de maquina
• version actual y metadata de build

Si te saltas ese paso, empujas errores de entorno a la parte mas cara del flujo.

2. Descubre el alcance antes de convertir nada

La guia de primeros pasos y la de workflows colocan el descubrimiento antes de la conversion. Manten ese habito.

acs2md space list --format json --limit 5
acs2md space pages by-key DOCS --tree

Por que importa:

• confirma que estas exportando el espacio correcto
• permite que stakeholders revisen la jerarquia antes del run
• reduce exportaciones accidentales durante migraciones o trabajo con cliente

Cuando la gobernanza importa, amplia tambien esa superficie:

acs2md space properties by-key DOCS --format json
acs2md space permissions by-key DOCS --resolve-users --format json

Asi traes metadatos y permisos dentro del mismo programa de exportacion.

3. Decide el contrato de salida antes de elegir flags

Muchos equipos eligen flags uno por uno. Un enfoque mejor es decidir que debe representar el directorio final.

Ejemplos:

• un espejo vivo de documentacion: usa --sync, conserva --rewrite-links, usa un directorio estable
• un archivo a largo plazo: conserva el comportamiento incremental por defecto o pasa --incremental
• un corpus RAG: usa --exclude-marks, a menudo desactiva imagenes embebidas y mantén refrescos previsibles
• un staging de migracion: incluye metadatos para no perder identificadores ni fechas

El contrato de salida debe dirigir los flags, no al reves.

4. Saca los secretos del historial del shell cuando puedas

La documentacion de configuracion recomienda una separacion limpia:

• dejar defaults no secretos en el archivo de configuracion
• inyectar secretos por variables de entorno cuando sea posible
• usar flags CLI para overrides puntuales y depuracion

Eso es especialmente util en CI/CD:

export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACS2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN

Si necesitas entornos separados en una sola maquina, usa --config-file en lugar de editar a mano el mismo config una y otra vez.

5. Elige un directorio estable para trabajos recurrentes

El seguimiento de estado depende de un directorio estable porque .convert-sync-state.json vive junto al Markdown exportado.

De ahi salen dos reglas practicas:

• mantén el mismo --output-dir cuando quieras refrescos solo sobre cambios
• evita --conflict-resolution=versioned si esperas que sync o incremental sigan funcionando, porque un directorio con timestamp no es un hogar estable para el state file

Es un punto sutil, pero afecta directamente a la eficiencia de ejecuciones futuras.

6. Haz que logs y support bundles sean rutina, no excepcion

Los trabajos masivos son mas faciles de confiar cuando dejan evidencia.

acs2md space convert by-key DOCS --output-dir ./docs --log-file acs2md.log
acs2md support --log-file acs2md.log --output bundle.txt

El bundle de soporte incluye configuracion enmascarada, diagnostico, contexto del entorno y logs recientes. Es valioso incluso dentro de tu propio equipo antes de pensar en soporte externo.

7. Separa workflows por objetivo

La pagina de workflows es util precisamente porque no finge que un solo perfil de exportacion sirve para todo.

Usa comandos o destinos distintos segun el objetivo:

• copia de continuidad: --sync
• archivo con retencion: --incremental
• planificacion de migracion: space pages --tree, luego space convert --include-metadata
• analisis de ingenieria nativa: space get --format atlas_doc_format
• revision de gobernanza: space list, space properties, space permissions

Cuando cambia el objetivo, debe cambiar tambien el contrato de salida.

Una checklist corta para operadores

Antes de una ejecucion real, confirma que todo esto sea verdad:

• doctor pasa
• el espacio correcto se confirmo con space list y space pages
• el modo es explicito cuando el borrado importa
• los secretos viven en config o variables, no copiados en notas
• hay logs activados para ejecuciones recurrentes o importantes
• el directorio destino es estable para el seguimiento de estado

Si incluso uno de estos puntos no esta claro, para y corrigelo antes de exportar.

Como mapear estas practicas a controles ISO 27001 y SOC 2

Cada una de las practicas anteriores tambien es una declaracion de control que un auditor puede verificar. Si operas dentro de un programa ISO 27001, ISO 27017, NIS 2 o SOC 2, asi se alinean las siete:

El mensaje practico es que no hay un “modo cumplimiento” extra que activar. El flujo defendible y el flujo productivo son el mismo flujo cuando eliges los valores por defecto correctos.

Recomendacion final

La mejor practica con acs2md no es un flag concreto. Es disciplina operativa. Los equipos que mas provecho le sacan son los que validan la maquina, confirman alcance, eligen bien el contrato espejo-o-archivo y guardan suficiente logging como para explicar luego lo ocurrido.

Asi es como una herramienta de conversion se convierte en una operacion documental confiable.