Annexe - docs as code - documenter plus en détail la méthode et les outils pour débuter

[mborne]

Motivation

• Demande en ce sens sur la précédente session
• Disponibilité de la fonctionnalité "GitLab pages" ou "GitHub pages" sur les nouvelles forges

Objectifs

• Comprendre l'intérêt et les limites de docs as code
• Pouvoir débuter facilement sans écrire du code

Actions

• Confirmer l'intérêt de traiter pour la prochaine session
•  Ajouter une section dédiée à docs as code en annexe
•  Faire une mindmap pour poser le plan (draft)
•  Ajouter une fiche en annexe sur les principes de docs as code

Draft

• Introduction
  • Plusieurs méthodes de gestion des documents
    • Suite bureautique
    • Suite bureautique SaaS
    • Wiki
    • Docs as code
  • Mauvaises pratiques récurrentes avec les suites bureautiques
• Les principes et l'intérêt de la méthode

Prendre les items de Docs as Code et détailler l'intérêt

• Méthodes de mise en oeuvre
  • Se contenter du rendu à la volée du gestionnaire de code
  • Générer un site statique et l'exposer avec sa fonctionnalité pages
  • Déployer un service dédié au rendu (ex : générateurs de site/blogs)
  • Intégrer le rendu dans une application existante (ex : bibliothèques markdown -> html)

Faire une fiche pour chaque en pointant sur des exemples

• Aller plus loin...

  • Stocker des schémas éditables (.drawio.png) ou les générer ( diagrams )
  • Stocker les données tabulaires au format CSV
  • Stocker les données complexes au format JSON (ex : projections cartographique) ou YAML ( ex : backstage de spotify pour la cartographie du SI, données de dimensionnement exploitée par Terraform,... )

• Les limites de la méthode (ergonomie d'édition, commentaires, révisions...)

• Conclusion (type de document où c'est adapté... à date?)