Skip to content

Manual de uso para subir información a los servidores de documentos usando Ansible

Prerrequisitos

1- Tener wsl instalado en el ordenador

2- Instalar git y ansible

3- Clonar el repositorio

3.1- Ir un directorio y abrir la terminal de windows

Figura 1 Abrir la terminal de windows.
Figura 1. Abrir la terminal de windows.

3.2- Clonamos el repositorio (git clone https://gitlab.generalsoftwareinc.comnoswork/upload-manuals-with-ansible)

Figura 2 Clonando el repositorio.
Figura 2. Clonando el repositorio.

3.3- Ingresamos las credenciales para que inicie la descarga de los archivos.

Figura 3 Ingresando las credenciales.
Figura 3. Ingresando las credenciales.

Procedimiento:

1- Copiar los archivos para el directorio files/

Después de haber clonado el repositorio entramos en la carpeta que se descargó.
A continuación entramos al directorio files/

Figura 4 Entramos al directorio files.
Figura 4. Entramos al directorio files.

En files/ debemos copiar:

  • Los dos archivos .md (en inglés y español)

  • Los dos archivos .pfd (en inglés y español)

  • Los dos archivos comprimidos con las imágenes (en inglés y español) (Son válidos todos los formatos de compresión)

Figura 5 Copiando los archivos.
Figura 5. Copiando los archivos.

2- Modificar el archivo de variables

2.1) Abrimos el archivo que se encuentra en la ruta vars/main.yml

Figura 6 Abriendo el archivo.
Figura 6. Abriendo el archivo.

El archivo contiene variables que deben modificarse acorde a los nombres de los archivos que copiamos en files/. Es importante tener en cuenta que cada variable tiene una descripción de qué es y cómo rellenarla. Específicamente las variables archivo_md_es y archivo_md_en aclaran que no debe escribirse la extensión .md en su contenido.

2.2) Modificamos el archivo vars/main.yml acorde al manual que desamos subir.

Figura 7 Modificando el archivo.
Figura 7. Modificando el archivo de variables.

3- Correr el playbook

3.1) Abrir la terminal de windows en el directorio raíz que descargamos

Figura 8 Abriendo la terminal de windows.
Figura 8. Abriendo la terminal de windows.

3.2) Acceder a la terminal de linux

En la terminal de windows escribimos "wsl"

Figura 9 Accediendo a la terminal de linux.
Figura 9. Accediendo a la terminal de linux.

3.3- Escribimos en la terminal de linux "ansible-playbook -i hosts.ini main.yml" y damos ENTER

Figura 10 Ejecutando el playbook.
Figura 10. Ejecutando el playbook.

De inmediato ansible comenzará a ejecutar las tareas necesarias para publicar los manuales

Buenas pácticas para redactar los manuales

Recomendamos seguir la siguiente estructura de archivos

Figura 11 Estructura de archivos.
Figura 11. Estructura de archivos.
Figura 12 Cómo referenciar una imagen.
Figura 12. Cómo referenciar una imagen.

1) Recordar que es importante cambiar la palabra "Manual" por el nombre real del manual o uno alternativo más corto que lo identifique.

2) Para nombrar todos los archivos deben usarse guiones bajos en lugar de los espacios en blanco: Ejemplo --> ESP_Manual.md

3) Las versiones en inglés y español de un manual se suben juntas como se ha indicado en el tutorial.

4) Dos manuales, uno para PC y otro para mobile se consideran manuales diferentes y se deben subirse por separado.

5) Al respetar la estructura de directorios y archivos según ilustra el esquema anterior se facilita la subida de los manuales, especialmente si lo va a subir una tercera persona.