Saltar a contenido

Cómo escribir documentación en SogetiLabs

Esta documentación está escrita usando Material for MKDocs. Para poder colaborar con la documentación se debe bajar el proyecto SogetiLabsDocumentation y seguir los siguientes pasos:

Preview mode

pip install -r requirements.txt
mkdocs serve

docker build -t mkdocs-custom .
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-custom

Esto desplegará un servidor web en nuestra máquina local (http://localhost:8000) que nos permitirá ir creando la documentación y poderla previsualizar en tiempo real.

Trabajar con ramas

Cada persona debe trabajar en su propia rama, que deberá crear a partir de la rama master (la puede llamar como quiera, como por ejemplo, su nombre, y así poder reutilizarla) subir todos los cambios a dicha rama y solicitar un PR para su validación y despliegue en producción (ver Despliegue de nueva documentación)

Estructura de los documentos

MkDocs ofrece una forma muy fácil de crear documentación, ya que sigue la sintaxis de Markdown para su escritura, y la propia estructura de ficheros para la navegación.

A la hora de estructurar los documentos se deben tener en cuenta algunos puntos:

Árbol de ficheros

El proyecto tiene una estructura (árbol) como la siguiente:

.
├─ docs/ #(1)!
│  ├─ assets/ #(2)!
│  │ ├─ images/
│  │ │ └─ ...
│  ├─ Documentación Técnica/ #(3)!
│  │ ├─ Extractores de datos/ #(4)!
│  │ │ ├─ Azure Extractor.md #(5)!
│  │ │ └─ Jira Extractor.md
│  ├─ Proyectos/
│  │ ├─ AIPlayground/
│  │ │ ├─ 1. General Chat.md
│  │ │ ├─ 2. Text Document Chat.md
│  │ │ ├─ ...
│  │ │ └─ index.md #(6)!
│  └─ index.md
├─ templates/
│  └─ target blank.md
├─ azure-pipelines.yml
├─ Dockerfile
├─ mkdoks.yml
├─ README
└─ requirements.txt
  1. Carpeta raíz donde se debe ir creando la documentación
  2. Carpeta para añadir assets (no se muestra en el menú de navegación)
  3. Sección principal (primer nivel) que se mostrará el menú lateral y la barra superior de navegación
  4. Subsección que se mostrará en el menú lateral, dentro de la sección padre principal
  5. Documento que pertenece a una sección (aparecerá en el menú de navegación)
  6. Documento principal asociado a la sección, llamado index.md (no aparece en el menú de navegación)

La carpeta donde debe ubicarse la documentación es la carpeta docs. En ella, cada nueva carpeta (excepto assets y alguna otra reservada) creará un nuevo nivel dentro del árbol de navegación de la página final, siguiendo un orden alfabético, aunque es posible controlar cierto orden de los documentos, explicado un poco más abajo.

Índice de carpeta/sección

Si queremos que la carpeta/sección tenga "per se" un documento asociado, deberemos crear dentro de la misma un fichero "index.md". Este se asociará directamente a la carpeta/sección y hará que la misma sea clicable y, por tanto, pueda contener información.

Si no existe ningún index.md dentro de alguna carpeta, esta actuará únicamente como desplegable.

Nombre de los documentos

Por defecto, el nombre que aparece en el árbol es el nombre del documento, a menos que este tenga un título (H1). En ese caso, el nombre que aparecerá en el árbol será dicho título.

Esto nos permite ordenar los ficheros usando una notación numérica (1., 2.,...) sin que aparezca dicho número en la navegación (ver sección AIPlayground)

Formatos dentro de la documentación

Es posible aplicar ciertos formatos y añadir cierto diseño dentro de los documentos, como tablas, bloques de código, imágenes, etc.

Imágenes y ficheros

Es posible incrustar imágenes o añadir ficheros para su descarga. En ese caso, deben ubicarse en una carpeta llamada z_attachments, dentro de la carpeta padre donde se encuentre el documento.

De esta manera será más fácil encontrar y gestionar dichas imágenes y ficheros.

Los documentos Spider Links Checker y Spider Links Checker - Documentación técnica tienen varios ejemplos.

Para ver todas las opciones posibles, se puede consultar la documentación oficial.

Qué usar para escribir documentación

Al estar escrita en sintaxis Markdown, podemos escribirla con cualquier editor de texto plano, pero es recomendable usar alguna herramienta que facilite la escritura, como VSCode u Obsidian.

Si se usa esta última, deben tenerse en cuenta algunas configuraciones:

  • Automatically update internal links: enabled
  • New link format: Relative path to file
  • Use [[wikilinks]]: disabled
  • Detect all file extensions: enabled
  • Default location for new attachments: In subfolder under current folder
    • Subfolder name: z_attachments

En las opciones de "Appearance"

  • Show inline title: disabled

Recomendable usar Obsidian

Se recomienda usar Obsidian como editor ya que nos facilita no sólo la escritura y previsualización, sino otros aspectos importantes como la actualización de enlaces en caso de que decidamos mover un documento a otra ubicación

Plugins Obsidian

Si se usa Obsidian como editor de texto, hay algunos plugins que puede ser de utilidad:

  • Advanced Tables: permite crear tablas muy fácilmente
  • Templater: permite usar plantillas. En la bóveda del repo existen algunas ya creadas
  • LanguageTool: corrector ortográfico de Language Tool

Se pueden usar otros plugins siempre y cuando no añadan al documento funcionalidades extras que no estén soportadas por Markdown de forma nativa. Por ejemplo, el plugin "Dataview" NO puede ser usado.

Despliegue de nueva documentación

Una vez hemos terminado de crear nuestra documentación debemos subir los cambios al repositorio. Lo haremos a nuestra rama, y abriremos una nueva PR para validar que todo está correcto.

Una vez validado, se hará el merge a master y el despliegue será automático, pudiéndose consultar la nueva versión en https://docslabs.sogeti.es.

Esta documentación estará accesible de varias maneras:

  1. Desde la VPN de Sogeti se podrá acceder libremente a toda la documentación EXCEPTO a la Documentación Técnica. Para ello será necesario estar logeado la cuenta del Lab
  2. Desde fuera de la VPN, únicamente los integrantes del Lab podrán tener acceso a toda la documentación, previo login.