Quel architecture de l'information vous utilisez pour la documentation de votre systeme

#1

Salut a tous,

Il a un sujet que je tente de creuser depuis longtemps, mais je n’y arrive pas trop, aussi par manque de vrai ressource sur le sujet, c’est l’architecture de l’information du documentation.

L’architecture de l’information est la façon dont une documentation (peut importe sa forme) est organisée, Le table of content d’un document par exemple est l’architecture de l’information de votre document.

Actuellement je travail sur un système extrêmement complexe, et la documentation de ce système a été fait de façon organique. C’est donc super dur de remettre de l’ordre dedans, mais en plus il n’y a pas vraiment “d’ordre” définie.

Du coup j’aimerai bien avoir des exemples de documentation interne ou savoir comment vous organisez la documentation d’un système complexe.

Ou a quoi ressemblerai votre parfaite documentation

1 « J'aime »
#2

Salut!

Voici quelques pistes que j’ai mis en place :

1- définir un outil unique où ranger tous les documents!

2- définir des types de documents avec leurs templates:
1- politiques: j’ai du mal à écrire ça, c’est plutôt stratégique et général. Il ne faut pas y citer d’outils, le but de la politique est d’être plutôt destinée au haut management
2- processus: les flux de travail qui découlent d’une politique. Plutôt destiné au management.
3- procédure: le plus important. Comment exécuter une tâche d’un processus. C’est un document non ambiguë, précis, concis, qui peut permettre à n’importe qui d’exécuter une tâche correctement.
4- release: une procédure, mais qui ne sert que pour une release particulière d’un produit. Donc jetée une fois la release faite.
5- base de connaissance: tout ce qui peut aider à comprendre un outil: une architecture, des explications sur son fonctionnement…
6- projet: Doc de réflexion sur un futur projet. Généralement, si le projet est lancé et fait, ça devient une base de connaissance.

3- définir un workflow pour le statut des docs (draft, validate, archives), le versioning, les règles de nommage des documents

4- écrire ta bible: la procédure de documentation ^^

5- comment lier les documents entre eux (j’utilise Notion pour stocker les documents, ça permet de faire des liens)

#3

Alors je suis d’accord avec ta classification, mais c’est justement sur la partie 5 base de connaisance que je bloque.

Pour un systeme assez simple, comme un site wordpress disont, la base de connaissance pourrai avoir un peu pret ce type d’architecture de l’information:

  1. Introduction au service
  2. Architecture du système
  3. Gestion des bases de données
  4. Sécurité
  5. Monitoring
  6. Support (procedure, aide a la resolution d’incident)
  7. Maintenance et mise à niveau

Mais meme la pour une application simple, ca me semble assez limite. Et pour une application encore plus complexe, ca me semble totalement inapplicable.

Apres je me dis, que peut etre qu’il ne faut pas une architecture comme si j’ecrivais un sommaire, mais plus des sorte de tag, un peu comme ici sur se forum, et je met 1 ou plusieurs tag a une page de documentation, ca permet de ne pas se soucier ou une page est ranger, mais peut quand meme aider a s’y retrouver.

Quelqu’un a deja utilsier un systeme similaire peut etre ?

#4

Oui, un système de tag fonctionne bien. Mais quand il y a beaucoup de document, ça peut devenir un casse tête pour retrouver les bons tag à mettre dans sa recherche. Et quand on a plusieurs dizaines de tags, aïe aïe aïe. ^^

J’ai pu utiliser Google workspace et notion, et pour retrouver un document, ils ont leur propre moteur de recherche qui est efficace. Et ça n’empêche pas l’utilisation de tags.

1 « J'aime »
#5

la base de connaissance étant un truc essentiel et parfois très dynamique (changement presque quotidien chez nous) je lui donne la forme d’un wiki. ça reste un point d’entré unique, mis a jour facilement par les admins/devops, avec historique des changement, et consultable par qui on veux.

#6

Mais comment tu sais une fois sur wiki.com ou aller chercher une information ? Ok les moteurs de recherche sont de plus en plus performants, mais même comme ça tu as besoin d’une classification non ?

Je pense que je vais commencer à imaginer une liste de tag possible, mais sans savoir exactement quel peut être une liste ni trop longue ni trop courte, l’équilibre va être je pense difficile à trouver.

Mon arborescence sera alors plutôt une liste à plat avec la définition des différents tags, ça peut fonctionner

#7

tu as tout a fait raison.
J’ai au départ un double index. un index des sites et un index des clients.
ensuite les dossiers sont constitués de plusieurs documents type, architecture, technologie mise en œuvre, spécificités, etc.
Avec ça on s’y retrouve. de plus comme tu le mentionne le moteur de recherche est efficace. Au final le wiki est plus pratique qu’une somme de document tableur, texte enrichis, présentation. Et de toute façon il est assez aisé d’ajouter un tel document dans le Wiki (mais il faut penser a y mettre les bon mot clef pour l’indexation.

2 « J'aime »
#8

Sujet super intéressant, en plus, personnellement, je déteste faire la doc.

J’essaie d’avoir une structure pas trop grosse, je me contente souvent d’un LLD et HLD. J’évite en général d’avoir les procédures d’installation dans la doc car c’est pénible à maintenir et avec l’IaC il n’y en a pas véritablement besoin à mon sens.

J’accorde plus d’importance aux procédures de résolution d’incidents car c’est en période de stresse qu’il faut éviter de trop réfléchir.

Sinon un système de tags me semble indispensable pour pouvoir effectuer des recherches faciles.