Avouons-le, la documentation est souvent une source de frustration pour les équipes agiles. Est-elle à jour ? Est-elle exacte ? N’est-elle pas obsolète ? … Je vous invite via cette présentation d’oublier la documentation classique et découvrir ou redécouvrir la documentation vivante (living doc) et comment elle contribue à l’agilité en favorisant la communication, la collaboration, l’adaptabilité et la transparence au sein d’une équipe. Ainsi elle aide à créer un environnement propice où les équipes peuvent réagir rapidement aux changements et de livrer de la valeur de manière continue.

1. 19 & 20 septembre 2023 - Paris, Niort
Living documentation au service de
l’agilité
Dorra Bartaguiz

2. PLATINUM SPONSOR
GOLD SPONSOR
SILVER SPONSOR
PARTENAIRE

3. DORRA BARTAGUIZ
• VP TECH (DIRECTION TECHNIQUE)
• CO-AUTEURE & ILLUSTRATRICE
• DIFFÉRENTS RÔLES
• DEV/ARCHI
• COACH/ FORMATRICE
• REVIEWER DE PROGRAMMEZ!
• PROF EN ÉCOLE D’INGÉ

4. Formation
Sessions intra
et inter-entreprise,
sur site ou à distance
Coaching
Mentoring et
accompagnement
sur le terrain
Projet
Engagement de moyens et
engagement de qualité
Conseil
Diagnostic et études
sur mesure
Nos domaines d’expertise
Attitudes et pratiques craft
NOS FORMATS D’INTERVENTION

5. PREMIÈRE JOURNÉE
DANS UNE ÉQUIPE

6. PETIT DÉJEUNER
https://www.pinterest.fr/pin/10907224090018175/
Accueil chaleureux Longue pause-café
le matin
Qui est qui ?

7. PETITES BLAGUES
Brise-glace

8. C’EST PARTI !

9. SUR MON BUREAU
DOC DU PROJET
https://www.pinterest.fr/pin/749497562969339085/

10. UNE JOURNÉE DE
LECTURE
ET PLEIN DE QUESTIONS
https://www.pinterest.fr/pin/375558056417732679/

11. DOCUMENTATION
SOURCE DE RÉPONSES OU QUESTIONS ?

12. SOURCE DE FRUSTRATION

13. SOURCE DE FRUSTRATION
QUI LA CONSOMME
A jour ?
Obsolète ?

14. SOURCE DE FRUSTRATION
QUI LA PRODUIT
Pas le
temps
Pas l’envie

15. SOURCE DE FRUSTRATION
POUR TOUT LE MONDE
Pas le
temps
Pas l’envie
A jour ?
Obsolète ?

16. BUT DE LA
DOCUMENTATION
TRANSMISSION
ACCESSIBILITÉ
MÉMOIRE DU FUTUR
CONFORME À L’ATTENDU

17. SHARED DOCUMENTS AREN’T
SHARED UNDERSTANDING
@JEFFPATTON
TRANSMISSION

18. TRANSMISSION
« Software Craft » Martraire, Thiéfaine, Bartaguiz, Hiegel, Fakih - Dunod

19. ACCESSIBILITÉ
https://wanderlustale.com/labbaye-dadmont-le-tresor-cache-de-lautriche/

20. MÉMOIRE DU
FUTUR

21. CONFORME À L’ATTENDU

22. REVENONS AU
MANIFESTE AGILE

23. AGILE MANIFESTO
• INDIVIDUALS AND INTERACTIONS OVER PROCESSES AND TOOLS
• WORKING SOFTWARE OVER COMPREHENSIVE DOCUMENTATION
• CUSTOMER COLLABORATION OVER CONTRACT NEGOCIATION
• RESPONDING TO CHANGE OVER FOLLOWING A PLAN

24. WE EMBRACE
DOCUMENTATION, BUT NOT
HUNDREDS OF PAGES OF
NEVER-MAINTAINED AND
RARELY-USED TOMES.
HTTPS://AGILEMANIFESTO.ORG/HISTORY.HTML

25. DOCUMENTATION MANUELLE

26. TROP D’ÉNERGIE GASPILLÉE

27. COMMENT ÉCONOMISER
L'ÉNERGIE ?

28. LIVING DOCUMENTATION
=
DOCUMENTATION
VIVANTE

29. CIBLE DE LA DOCUMENTATION

30. ENSEMBLE DES OPÉRATIONS, DES
MÉTHODES, ETC., QUI FACILITENT LA
COLLECTE, LE STOCKAGE, LA RECHERCHE
ET LA CIRCULATION DES DOCUMENTS ET
DE L'INFORMATION
HTTPS://WWW.LAROUSSE.FR/
DOCUMENTATION

31. MA DÉFINITION DE LA DOCUMENTATION
• CRISTALLISATION DE DISCUSSIONS CHOISIES ENTRE DEUX PARTIES
• CR DE RÉUNIONS, SPÉCIFICATION/CONTRAT ENTRE DEUX PARTIES…
• SIMPLIFICATION D’UNE INFORMATION POUR UNE POPULATION
• DÉFINITIONS, SCHÉMAS, EXEMPLES…
• UNE MÊME INFORMATION PEUT ÊTRE DÉCRITE DE PLUSIEURS FAÇONS

32. IDENTIFIER LA CIBLE DE LA
DOCUMENTATION

33. EXEMPLE EN CHIMIE

34. UNE DOC PAR RELATION
Schéma

35. DOCUMENTATION
VIVANTE ?

36. POPULARISÉ AVEC
HTML
Documentation
Scénarios
Gherkin
Specflow Living Doc/
Cucumber & Pickles

37. Exemples
Scénarios
Gherkin
Tests
automatisés
Documentation
générée
Besoin
Expliciter via
Formaliser en
Automatiser
Transformer
Présenter

38. SPECIFICATION BY EXAMPLE HELPS TEAMS
ESTABLISH A COLLABORATIVE SPECIFICATION
PROCESS THAT LOWERS PROBLEMS IN THE
MIDDLE OF AN ITERATION […] AND DOESN’T
REQUIRE MONTHS OF WRITING LONG
DOCUMENTS.
GOJKO ADZIC
« SPECIFICATION BY EXAMPLE »

39. LIVING DOCUMENTATION
=
EVERGREEN
DOCUMENTATION

40. DOCUMENTATION
SYSTÈME

41. SYSTÈME
DOCUMENTATION

42. LIVING DOCUMENTATION
=
PLUS DE TRANSPARENCE

44. EXEMPLE DE LIVING
DOCUMENTATION
CURRENCY CONVERTER
-
DÉMO GHERKIN

45. SCENARIO: SIMPLE CONVERSION ROUNDING TO CENTS
GIVEN THE EUR TO USD EXCHANGE RATE IS 1.1329
WHEN I CONVERT 10 EUR TO USD BY ROUNDING TO CENTS
THEN I GET 11.33 USD
EXEMPLE SCÉNARIO GHERKIN

46. GIVEN THE EUR TO USD EXCHANGE RATE IS 1.1329
[GIVEN("THE (.*) TO (.*) EXCHANGE RATE IS (.*)")]
PUBLIC VOID GIVENTHEEXCHANGERATEIS
(STRING SOURCECURRENCY, STRING TARGETCURRENCY, DECIMAL RATE)
EXEMPLE SCÉNARIO GHERKIN

47. EXEMPLE SCÉNARIO GHERKIN

48. LIVINGDOC
FEATURE-FOLDER <<REPERTOIRE_FEATURES>>
-T <<TEST_EXECUTION.JSON>>
--OUTPUT <<DOC.HTML>>
EXEMPLE SCÉNARIO GHERKIN

52. S’OCCUPER DE LA
DOCUMENTATION
VIVANTE

53. BESOIN DE SOINS
• CODE DE GÉNÉRATION DE DOC
» À ÉCRIRE
» À MAINTENIR
» SI EXTERNALISÉ, AVEC SES PROPRES TESTS
» À SIMPLIFIER : MINIMUM D’EFFORT
• PRÊT À ÊTRE SUPPRIMÉ
» PERSONNE N’EN A PLUS BESOIN
» IMPORTANCE DE SIMPLICITÉ

54. Exemples
Scénarios
Gherkin
Tests
automatisés
Documentation
générée
Besoin
Expliciter via
Formaliser en
Automatiser
Transformer
Présenter
Atelier :
Example mapping
Acteurs :
• DEV
• PO
• QA

55. LIVING DOCUMENTATION
=
PLUS DE COMMUNICATION

57. POPULARISÉ AVEC
HTML
Documentation
Scénarii
Gherkin
Specflow Living Doc/
Cucumber & Pickles

58. GÉNÉRALISÉ AU-DELÀ DES SPECS
Générateur
Code
Production
Base
Sprints
Documentation
Calendrier
Schéma

59. IT’S POSSIBLE TO GET THE SAME BENEFITS OF LIVING
DOCUMENTATION FOR ALL ASPECTS OF A
SOFTWARE DEVELOPMENT PROJECT: BUSINESS
BEHAVIORS, OF COURSE, BUT ALSO BUSINESS
DOMAINS, PROJECT VISION AND BUSINESS DRIVERS,
DESIGN AND ARCHITECTURE, LEGACY STRATEGIES,
CODING GUIDELINES, DEPLOYMENT AND
INFRASTRUCTURE.
CYRILLE MARTRAIRE
« LIVING DOCUMENTATION »

60. DÉMO ARCHI
EXEMPLE DE LIVING
DOCUMENTATION
CURRENCY CONVERTER
-

61. https://github.com/iAmDorra/CurrencyConverter/blob/master/CurrencyConverter.LivingDocumentation/HexagonalArchiDocument.cs

62. DÉMO GUIDED TOUR
EXEMPLE DE LIVING
DOCUMENTATION
CURRENCY CONVERTER
-

63. https://github.com/iAmDorra/
CurrencyConverter/blob/master/
CurrencyConverter.LivingDocumentation/
GuidedTourDocument.cs

64. DÉMO
MANUEL D’UTILISATION
EXEMPLE DE LIVING
DOCUMENTATION
CURRENCY CONVERTER
-

65. https://github.com/iAmDorra/CurrencyConverter/blob/master/
CurrencyConverter.Web.Tests/SeleniumTest.cs

66. PAR OÙ COMMENCER ?
Code
Production
Base
Sprints
Documentation
Calendrier
Schéma

67. IDENTIFIER LE BESOIN
• A LA RÉTRO, AU DAILY MEETING…
• IDENTIFIER LES PARTIES OBSCURES
• ETONNEMENT DES NOUVELLES ARRIVÉES
• LES ANCIENS MEMBRES AUSSI
• IDENTIFIER LES CONNAISSANCES NON PARTAGÉES
• CONNAISSANCES CHEZ UNE SEULE PERSONNE OU PETIT GROUPE
• LES POINTS DE BLOCAGE RÉCURRENTS

68. TROUVER UNE SOLUTION
• IDENTIFIER QUELLE DOCUMENTATION CRÉER
• IDENTIFIER LA CIBLE DE LA DOCUMENTATION
• CHERCHER À AUTOMATISER LA GÉNÉRATION
Ne pas le faire seul.e !
Utilisez la dynamique du groupe

69. LIVING DOCUMENTATION
=
PLUS DE COLLABORATION

71. STRATÉGIE DE
DOCUMENTATION

72. QUESTIONS À SE POSER
On me
demande
une doc ?
La cible
de la doc
est
précise ?
Ne pas faire de doc
Non
Oui
Non /A tout le monde
Oui

73. QUESTIONS À SE POSER
On a besoin
d’une doc
pour se
rassurer ?
Gérer le pb de
confiance avant !
Oui
Non
Cible identifiée
Tant mieux
Mieux collaborer
Le partage
peut passer
par de la
conversation/
collaboration
?
Oui
Non

74. QUESTIONS À SE POSER
La source de
l’information
est identifiée
?
L’information est
exploitable en
l’état ?
Ne pas faire de doc
Identifier la source avant
Non
Oui
Doc nécessaire et
irremplaçable par
de la conversation/
collaboration
Non
Augmenter/réorganiser
la source d’info
Oui

75. QUESTIONS À SE POSER
Information
exploitable
ou augmentée
L’information
est stable ?
L’information
est
redondante ?
Variabiliser les infos
Non, volatile
Oui, stable
Oui
Non
Générer de la doc
Vérifier la cohérence entre
sources

76. PRINCIPES DE LA
DOCUMENTATION
VIVANTE

77. Insightful
Low effort
Collaborative
Reliable
Réduction du temps lié à
la rédaction/mise à jour
de la documentation
Fiable, précise et
synchronisée avec le
livrable à tout moment.
Idée claire,
prise de décision
délibérée
Favoriser les échanges,
la construction collective

78. LIVING DOCUMENTATION
=
PLUS DE TRANSPARENCE
PLUS DE COMMUNICATION
PLUS DE COLLABORATION

79. MERCI
* TOUTES LES ILLUSTRATIONS SONT RÉALISÉES PAR MES SOINS
* HTTPS://GITHUB.COM/IAMDORRA/CURRENCYCONVERTER
VOS FEEDBACKS