Comment le SIA organise la documentation de son infrastructure

compte_SIA

L'organisation est directement inspirée du système Divio. Nous y avons ajouté les procédures et les conventions.

Les tutoriels, explications, how-to guides et références sont les éléments définis par le système Divio. En voici un petit récapitulatif :

• tutoriels : pour apprendre aux nouveaux à utiliser l'outil
  • utile lorsque l'on étudie
  • suite d'instructions
• explications : pour comprendre
  • utile lorsque l'on étudie
  • informations
• how-to guides : pour savoir comment faire une action / résoudre un problème
  • exemple : comment attribuer un VLAN à une VM sur Proxmox
  • utile lorsque l'on travaille
  • suite d'instructions
• références : description des détails techniques
  • utile lorsque l'on travaille
  • informations

Les procédures et les conventions sont des obligations spécifiques à une organisation :

• procédures : checklist d'action.s à effectuer obligatoirement avant ou après d'autres actions
  • exemple : lorsque vous changez la prod –> envoyez un message à l'équipe
  • utile lorsque l'on travaille
  • suite d'instructions
• conventions / politiques : façon de faire les choses
  • exemple : convention de nommage - quel nom de domaine donner à un service
  • utile lorsque l'on travaille
  • règles à respecter

Les éléments d'infrastructure sont tous les éléments qui supportent l'infrastructure. Cela concerne les éléments qui supportent d'autres services (par exemple le monitoring ou les backups), mais aussi les éléments qui aident les administrateurs à travailler (par exemple un outil de gestion des tâches).

• les explications sont distillées dans les références, les procédures et les politiques/conventions
• références :
  • lien vers l'implémentation
  • l'architecture
  • le.s logiciel.s - fonctionnalités recherchées
• procédures & conventions / politiques
• tutoriel : apprendre à utiliser un élément de l'infrastructure, souvent en lien avec d'autres services.
  • exemple : restaurer une backup
• how-to guides : en relation avec l'architecture, limitez les instructions spécifiques aux implémentations, pour cela faire des how-to dans les implémentations

Certains éléments de l'infrastructure sont documentés sur d'autres plateformes plus adaptées, par exemple les adresses IPs sont mieux documentés sur un IPAM. Le wiki étant la partie centrale de la documentation d'une infrastructure, il est important d'y indiquer quels éléments sont documentés sur quelles plateformes afin de les trouver facilement.

Il y a énormément d'éléments d'infrastructures. Pour l'instant, nous n'avons pas de groupage bien défini.

Une implémentation est l'ensemble des processus et ressources permettant d'implémenter un service. Par exemple le cluster openshift est une implémentation du service orchestration de containers.

La documentation publique est là pour documenter ce qui est générique au logiciel utilisé. Par exemple lorsque l'on utilise un logiciel, le meilleur emplacement pour le documenter est aux côtés de son code source (par exemple sur Github). Si la documentation n'est là que pour vous, où si vous n'avez pas envie d'attendre que la documentation officielle implémente ce que vous souhaitez marquer, la partie documentation-publique/software est là pour ça.

• les explications sont distillées dans les références, les procédures et les politiques/conventions
• les parties how-to guides et tutoriels doivent être spécifiques à l'implémentation
• références:
  • l'hébergement - sur quelle hôte / plateforme les processus s'exécutent
  • les interactions avec d'autres services
  • la configuration de l'implémentation
• conventions: ne concerne que ce qui est spécifique à l'implémentation. Vous pouvez lier les conventions plus génériques.
  • exemple : les conventions de nommage du cluster OKD seront ici
  • exemple : on lie la convention de nommage des comptes de service dans le cluster FreeIPA
• procédures: documente les procédures dont l'action principale est faîte sur l'implémentation
  • exemple : la procédure de déploiement d'un PVC sur OKD sera ici

Initialement, nous avions organisé notre documentation avec 4 dossiers racines : tuto, explication, how-to guides et références. Cela ne nous as pas semblé adapté car :

• lorsque l'on documentait, il y avait souvent un mix entre les références et les how-to
• au vu de la quantité d'éléments, il y énormément de context switching : on réapprend constamment à utiliser les outils, on regarde les procédures et les conventions, … Devoir accéder à une partie complètement différente de l'infrastructure était contraignant.
• cela n'était pas très accessible, car la plupart des informations étaient dans référence. Et la référence des logiciels des services infrastructures étaient dans références/services_infra/implementations

  * infrastructure
    * tutorials?
    * procédures globales
    * _infrastructureElement_ (ex: backup)
      * references with explications:
        * link to implementation
        * architecture
        * software requirements
      * conventions with explications
      * procedures with explications
      * how-to guides: 
      * tutorials
  * implementations
    * services_fournis
      * _serviceName_
      * _organisationName_ : lorsque nous hébergeons plusieurs services au profit d'une même organisation
        * _serviceName_
    * services_infra
      * _serviceName_

sia
- tutorial
- how-to
  - guides
  - procedures
- reference
  - conventions
  - elements_infra
    - _elementName_ (ex: central auth, ipam)
      - link to implementation
      - software requirements
  - services_infra
    - _serviceName_ (ex: freeipa cluster, netbox)
      - specific configuration
      - link to other services
  - services_asso
    - _serviceName_ (ex: site etu)