Repositorio de documentación técnica para el OCSD

Acerca de

Este repositorio de documentación continene información de utilidad para el equipo de protección integral de fundación Acceso para el manejo y registro de incidentes recibidos como parte de los esfuerzos del Observatorio Centroamericano de Seguridad Digital (OCSD).

Este repositorio se estructura y adapta a partir de la metodología diátaxis.

Alcance

Este repositorio contiene información específica para el OCSD, y complementa otros esfuerzos documentales dentro de Fundación Acceso.

El objetivo de este repositorio es facilitar el registro e intercambio de conocimientos dentro del equipo técnico, a fin de obtener mayor consistencia y rigurosidad en el manejo y la atención de incidentes.

La expectativa es que todas las personas del equipo de protección integral puedan contribuir, de forma tal que los aprendizajes de cada atención se sistematicen de forma clara, y se encuentren disponibles para que otras personas en la organización puedan beneficiarse del conocimiento colectivo.

Lineamientos de uso

Este es un repositorio privado para uso interno del equipo de protección integral. Todas las personas del equipo de protección integral recibirán una invitación para poder colaborar directamente con el repositorio.

Cuando se considere oportuno y pertinente, se podrá compartir conocimiento y artículos específicos con contrapartes, siempre y cuando estas acciones no conlleven ningún riesgo adicional para Fundación Acceso o las personas que apoya, y cuenten con la aprobación necesaria de la coordinación.

Implementación técnica

Para la implementación de este repositorio documental se utiliza el generador de sitios estáticos MKDocs Material, que a su vez expande y complementa el generador de sitios MKDocs.

Mkdocs, y la versión MKDocs material, permiten construir un sitio web estático a partir de una serie de documentos en formato MarkDown. Para este sitio en particular, alojamos los documentos en un proyecto privado de Gitlab, y utilizamos acciones automáticas para hacer el despliegue en Gitlab Pages.

Para el despliegue y construcción del sitio se utiliza la estructura base de MKDocs que consiste de:

• Carpeta '/docs': En esta carpeta se almacenan los archivos de documentación en formato MarkDown.
• Carpeta '/overrides': Permite almacenar configuraciones y archivos personalizados para MKdocs, como por ejemplo logos, etc.
• Archivo de configuración 'mkdocs.yml': Archivo principal de configuración para mkdocs-material, donde se especifican los parámetros y opciones para la construcción del sitio estático.

En resumen, el presente repositorio contiene la siguiente estructura:

.
├── docs
│   ├── assets
│   │   └── banner-home.jpg
│   ├── explicadores
│   │   └── explicador-1
│   │       └── index.md
│   ├── guias
│   │   └── guia-1
│   │       └── index.md
│   ├── referencias
│   │   └── referencia-1
│   │       └── index.md
│   ├── tutoriales
│   │   └── tutorial-1
│   │       └── index.md
│   └── index.md
├── mkdocs.yml
└── README.md

El detalle de configuraciones se encuentra documentado tanto en el sitio web de MKDocs-Material y MKDocs.

Integración continua en gitlab

Para realizar la integración continua en gitlab, se utiliza el siguiente script. En el se especifica que luego de cada commit al branch default del repo (en este caso main) se generará nuevamente el sitio dentro de la carpeta temporal 'public' de gitlab. Una vez que el contenido es generado por MKDocs Material, gitlab toma este conenido y lo despliega directamente en Github Pages.

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - ~/.cache/ 
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Lineamientos para contribuciones

Para organizar y alinear las contribuciones favor sigue los siguientes lineamientos:

• Usa el formato Markdown (.md) con sintaxis clara y correcta
• Escribe en español neutro
• Mantén la estructura de la documentación según el marco Diátaxis
• Si agregas archivos, usa nombres en minúsculas y con guiones medios, sin acentos ni caracteres especiales
• Al contribuir contenido nuevo, define si es un tutorial, how-to, explainer o referencia
• Incluye referencias y enlaces siempre que sea posible.

Flujo para contribuciones

A continuación detallamos los pasos necesarios para editar o agregar un nuevo recurso al respositorio de documentación. Como buena práctica, se recomienda trabajar sobre una nueva rama o branch, o en su defecto crear un fork del proyecto, y enviar los cambios como solicitudes de integración.

Editar un recurso

Si deseas editar un recurso basta con modificar el contenido del archivo fuente. Esto se puede hacer identiicando la ubicación el archivo correspondiente dentro de la carpeta '/docs', o utilizando el botón de edición (📝) que se despliega en la parte superior de cada uno de los recursos.

Agregar un nuevo recurso

Si deseas agregar un nuevo recurso sigue los siguientes pasos:

1. Crea una carpeta con el nombre para el nuevo recurso, siguiendo los lineamientos especificados más arriba. Por ejemplo: 'explainer-01-inteligencia-de-amenazas'.
2. Dentro de la carpeta, crea un nuevo documento llamado 'index.md'. Coloca en este documento el texto en formato Markdown para el nuevo recurso.
3. Incluye el nuevo recurso dentro de la navegación en el archivo 'mkdocs.yml'.

Una vez que guardes el nuevo recurso y lo incluyea en la configuración de MKDocs, los cambios se ejecutarán de forma automática y se actualizará el contenido del sitio web.

Elementos de creación y organización del contenido

La versión mkdocs material facilita varios elementos que permiten representar y organizar la información. La documentación correspondiente se puede consultar en la sección de referencias de Mkdocs Material.

En particular se pueden utilizar algunas de las siguientes opciones:

• Bloques de resalte o admonitions: Permiten resaltar elementos en bloques de diferentes tipos: notas, abstract, info, tip, success, etc. Por ejemplo, se pueden utilizar para resaltar rutas alternativas, ejemplos, posibles errores, entre otros.
• Tabs de Contenido: Se pueden utilizar para desplegar contenido en pestañas. Por ejemplo, esto puede ser de utilidad cuando se requiere desplegar instrucciones para diferentes sistemas operativos.
• Grids: Permiten organizar en grids o bloques, lo que permite resaltar y equiparar la importancia de diferentes elementos o bloques.
• Diagramas: Permiten generar diagramas a partir de una descripción de sintáxis.
• Bloques de código: Permiten representar bloques de código con la sintáxis adecuada. Además se describen algunos elementos que permiten copiar, resaltar o comentar líneas de código específicas.
• Íconos y emojis: Material para mkdocs permite agregar de forma muy sencilla más de 10,000 íconos.

Reporte de problemas y mantenimiento

El mantenimiento de este sitio de documentación estará a cargo del equipo de protección digital.

En caso de tener consultas generales sobre el uso de este repositorio, se recomienda primero consultar la documentación disponible.