Sommaire :

• Bientot la fin
• Un autre élément important avant la conclusion : la Doc-as-code
  • Le concept Doc-as-Code
  • Le bénéfice de la Doc-as-code
• Attaquons la conclusion et essayons de répondre à la promesse faite
  • Diataxis et le DAT
  • Doc-as-code et le DAT
  • Les ADR et le DAT
• Comment faire maintenant ?
  • Une proposition de structure documentaire

Bientot la fin

On approche de la fin.

Reprenons :

• On a parlé du DAT et de ses erreurs
• On a parlé de Diataxis, cette méthode d'organisation de la documentation (DES documentations)
• On a parlé des ADR (Architecture Decision Record)

Il nous reste à comprendre quoi en faire.
(même si vous avez déjà des idées qui germent des dernières lectures)

Un dernier élément bonus: la Doc-as-code

On fait du devops, de l'infra-as-code ...
Il manquait une transformation importante : la Doc-as-code.

Le concept Doc-as-Code

Le concept est simple :

S'appuyer sur des langages à faible balisage (Markdown, AsciiDoc) pour gérer le contenu riche comme du code et pouvoir y appliquer toutes les bonnes pratiques que l'on connait (versioning, publication, revue, merge, ...)

Ok, faisons au plus simple : "si je vous dis Wiki, Confluence, ..."

Pour l'explication détaillée, je vous partage cette série d'articles de mon collègue Nicolas Giraud :
https://dev.to/onepoint/doc-as-code-petit-guide-illustre-pour-mieux-se-lancer-2m2k

La Doc-as-code est-elle vraiment essentielle pour ça ?
Non, on peut se suffire d'une documentation collaborative (wiki, confluence).
La Doc-as-code apporte plus de gains et d'intégrations
Et elle permet de réduire le travers du "je ferais la doc plus tard"

Le bénéfice de la Doc-as-code

Avec cette Doc-as-code, on peut partager et inclure des documents dans des structures plus complexes.

On peut réaliser la doc en parallèle du code développé (et ce que, code applicatif ou infra)

Ces docs techniques pourront être versionnées, publiées dans des stratégies de construction documentaire de documentation plus large.

Comme on s'autorise à (ab)user des références et liens, les mises à jour se propagent sans effort documentaire supplémentaire.

Retenons : on peut écrire la doc en même temps que le code.
On peut ensuite publier/insérer la doc pour en générer de nouvelles.

Attaquons la conclusion et essayons de répondre à la promesse faite

Rappel de la promesse :

Et si on pouvait dépoussiérer le DAT et le transformer en un outil 
plus collaboratif, plus simple et qui prouverait son intérêt ?
Est-ce qu'on pourrait trouver plusieurs solutions actuelles pour faciliter la rédaction et la maintenance ?

Quels seraient les gains de chacun des différents produits évoqués pour la gestion du DAT ?

Diataxis et le DAT

Diataxis nous apporte une méthode de rédaction.
Avec cette méthode, on devrait éviter bon nombre d'erreurs évoquées.

Si on reprend Diataxis, on comprend ce qui pêche avec le DAT :

A-t-on assez réfléchi aux lecteurs quand on a rédigé le DAT ?

Le DAT doit répondre à la question "qu'est-ce que c'est ?"
Au sens Diataxis, le DAT est un document de Référence

Diataxis explique pour les Références :

• Devrait être austère, on ne lit pas une référence, on la consulte
• Décrire et seulement décrire
• Adopter un standard

• Respecter la structure de la mécanique sous-jacente

• Pas de pourquoi (c'est dans les concepts)

• Pas de procédure (c'est dans les guides)

Un DAT n'est pas fait pour expliquer les choix techniques de la plateforme.

De vous à moi, tous les DAT que j'ai lu et/ou rédigé sont très mauvais par rapport sur ça. On tente d'y fourrer les descriptions, les procédures, les choix d'architecture, etc.
Mais c'est intéressant :
on sait maintenant ce qu'on devrait placer et pas placer dans un DAT

Doc-as-code et le DAT

Si on reprend la Doc-as-code et le DAT, on a une première évidence :

Le DAT ancien en tant que document monolithe ne tient plus, il doit devenir partie intégrante de la documentation globale de la solution.

On peut identifier 2 stratégies :

• Construire sa documentation en suivant une hiérarchie reprenant les éléments de description du DAT

• Construire un index listant/pointant vers les éléments de référence répartis dans sa documentation qui servira de DAT.

Les ADR et le DAT

• Les ADR décrivent les concepts (pourquoi ?)
• Le DAT décrit les références (qu'est-ce que c'est ?)

Ils sont 2 formes de document différentes, liés sans se recouvrir.

Les ADR font partie de la documentation mais ne font pas partie du DAT.

Comment faire maintenant ?

Le DAT est mort, vive le DAT !
Ok, c'était facile :)

Si vous avez un document .doc(x) monolithique, vous pouvez le passer en "obsolete" et travailler à sa reconstruction :)

Que devient le DAT ?

En fait, le DAT "disparait" dans la documentation générale de la solution.

Est-ce encore utile de l'évoquer ? Je crois que le terme restera encore pas mal d'années.

Sur mes derniers projets, lorsque l'on me demande le DAT, je donne le lien vers la documentation technique

Quelle méthode pour mettre le DAT à jour et l'intégrer dans la documentation ?

Pas de secret, cela va participer à la refonte/l'évolution documentaire de la solution.

Glossaire :

• solutions : solution applicative/application, on parle de plus en plus de produit
• socle : socle technique, Kubernetes, réseau, hosting, sauvegarde, monitoring, logs, annuaire, ciam, etc.

0. Mettre en place une documentation légère permettant la Doc-as-code 
(wiki et équivalents)
1. Identifier vos solutions/socle
(La documentation se construit pour chaque solutions/socle)
2. Pour chaque solutions/socles, 
   faites un inventaire de la documentation existante
3. Identifier les formes de document existants
   3.1 Identifier les "tutoriels" existants  
   3.2 Identifier les "guides" existants  
   3.3 Identifier les "références" existants  
   3.4 Identifier les "concepts" existants  
4. ADR Documentation : Définisser une structure documentaire 
qui vous parait adaptée à vos besoins
5. Mettre la structure documentaire et déplacer les documents
5. Mettre à jour au fur et à mesure le contenu

Oui mais les échanges entre les solutions/socle, je les mets où ?

Identifier le responsable de ces échanges.
C'est lui qui portera la documentation de ces échanges.
Les autres pourront faire référence à cette documentation.

Une proposition de structure documentaire

Un exemple/proposition de structure documentaire qui suit la structure d'un DAT classique et qui permet de retrouver facilement ADR, DAT et DEX.

Concepts (ADR)
- Concepts applicatifs
    * ADR 1
    * ADR 2
- Concepts techniques
    * ADR 3
    * ADR 4
- Concepts migration
    * ADR 5
    * ADR 6
- Concepts exploitation
    * ADR 7
    * ADR 8

Reference (Architecture)
- Architecture fonctionnelle
    * Schéma d'architecture fonctionnelle
    * Composants fonctionnels
        * composant 1        
        * composant 2
- Architecture applicative
    * Schéma d'architecture applicatif
    * Composants applicatifs
        * composant 1        
        * composant 2
- Architecture technique
    * Schéma d'architecture technique
    * Composants techniques
        * composant 1        
        * composant 2
- Observabilité
- Finops
- SLA

Guides (Exploitation)
- Procédures techniques
- Procédure d'installation
- Procédure de migration
- Procédure observabilité
- Procédure sauvegarde
- Procédure Résilience

Nouvel arrivant (Tutoriel)
- Installer son poste
- Configurer ses accès

Fin

Voila, c'est fini pour cette série d'articles.
J'espère que cela vous aura apporté des réponses et que vous êtes aussi convaincus que moi.
N'hésitez pas à me laisser un commentaire/critique.