Ansible-como-herramienta-de-documentación.md

+> Adaptación y traducción al español del artículo [How to use Ansible to document procedures](https://opensource.com/article/19/4/ansible-procedures) de **opensource.com**
+
+#### En Ansible, la documentación es el *playbook*, por lo que la documentación evoluciona naturalmente junto con el código.
+
+Una de la razones por las que en el equipo de adminsys utilizamos Ansible para construir nuestra [*infraestructura como código*](https://en.wikipedia.org/wiki/Infrastructure_as_code), es que nos permite documentar con alta fidelidad los procedimientos desarrollados, tanto los que se usan con frecuencia como los que rara vez son utilizados. Este proceso facilita el trabajo y reduce el tiempo que lleva realizar tareas repetitivas, aquellas en las que se ejecutan comandos específicos en una secuencia determinada para lograr un resultado específico.
+
+Al documentar con Ansible, no es necesario registrar en otro sitio (por ej. issues o wikis) todos los parámetros para cada comando o todos los pasos involucrados en un procedimiento específico, y para todos los miembros del equipo es fácil compartir y entender en detalle lo que se está haciendo.
+
+Los enfoques tradicionales para la documentación, como wikis o unidades compartidas, son útiles para documentos generales, **pero inevitablemente se vuelven obsoletos y no pueden seguir el ritmo de los rápidos cambios en la infraestructura y los entornos.** Para procedimientos específicos, es mejor documentar directamente en el código utilizando una herramienta como Ansible.
+
+
+## Ventajas de Ansible para documentar
+
+Antes de comenzar, repasemos algunos conceptos básicos de Ansible: un *playbook* es una organización de procedimientos de alto nivel que utiliza *plays*; los *plays* son procedimientos específicos para un grupo de hosts. Las tareas (*tasks*) son acciones específicas, los módulos son unidades de código y el inventario es una lista de hosts administrados.
+
+**La gran ventaja de Ansible es que la documentación es el *playbook* en sí mismo**, lo que evoluciona está contenido dentro del código. Esto no solo es útil, sino también práctico, porque más que solo documentar soluciones con Ansible, se está codificando un *playbook* que permite escribir procedimientos y comandos deseados, reproducirlos y automatizarlos. De esta manera, se puede mirar seis meses hacia atrás, comprenderlos y ejecutarlos otra vez rápidamente.
+
+Es cierto que esta forma de resolver problemas puede llevar más tiempo al principio, pero **definitivamente ahorra mucho tiempo a largo plazo.** Al ser disciplinado para adoptar estos nuevos hábitos, se mejoran las habilidades en cada iteración.
+
+## Elementos importantes y herramientas que facilitan el proceso
+
+### Tener en mente la idempotencia
+
+En la *automatización de infraestructura*, la idempotencia significa alcanzar un estado final específico que **permanecerá igual, sin importar cuántas veces se ejecute el proceso.** Entonces, cuando se está automatizando un procedimiento, es importante tener en cuenta el resultado deseado para escribir el código que lo consiga de manera consistente.
+
+**Este concepto existe en la mayoría de los módulos de Ansible porque después de especificar el estado final deseado, Ansible lo logrará.** Por ejemplo, hay módulos para crear sistemas de archivos, modificar iptables y administrar entradas cron. Todos estos módulos son idempotentes por defecto, por lo que debe darles preferencia.
+
+Si se está utilizando alguno de los módulos de nivel inferior, como `command` o `shell`, o desarrollando módulos propios, es necesario ser cuidadoso de escribir código idempotente y seguro de repetir muchas veces para obtener el mismo resultado.
+
+El concepto de idempotencia es importante cuando prepara procedimientos para la automatización porque le permite evaluar varios escenarios e incorporar los que harán que su código sea más seguro y crear un nivel de abstracción que apunte al resultado deseado.
+
+### Control de código fuente
+
+Cuando se trabaja con *playbooks* Ansible, es muy importante acordar una estrategia de gestión de código. La solución escogida fue utilizar un repositorio Git. 
+
+Permite iterar sobre una solución para mejorarla y ofrece muchas ventajas para el trabajo colaborativo entre varios desarrolladores: visualizar el histórico de cambios, restaurar versiones anteriores, realizar copias de seguridad, etc.