OCTOFest 2024 | Living documentation, parce que la doc, ça peut être fun !

Vous êtes sur le point d'écrire de la doc ? Arrêtez immédiatement, vous risquez de créer de la documentation morte ! 🎃👻🧟

Si vous voulez fabriquer de la documentation pérenne, toujours à jour et synchronisée avec votre code, ce talk est fait pour vous : il y aura de la théorie et des exemples concrets de Living Documentation que j'applique quotidiennement dans plusieurs projets en production depuis 5 ans.

* Un talk joué devant une centaine de personnes chez OCTO Technology lors de la conférence interne OCTOFest en novembre 2024

Crédits images Unsplash :
* alexkondratiev : https://images.unsplash.com/photo-1554475901-4538ddfbccc2?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2372&q=80
* Hans-Peter Gauster (Unsplash) : https://images.unsplash.com/photo-1494059980473-813e73ee784b?q=80&w=2969&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D
* Ambitious Studio* | Rick Barrett (Unsplash) : https://images.unsplash.com/photo-1659088981163-7823b8d74fac?q=80&w=2970&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D

Transcript

1. LIVING DOCUMENTATION PARCE QUE LA DOC, ÇA PEUT ÊTRE FUN 1
2. $> WHOAMI 3
3. CONSULTANT @ OCTO DEPUIS 2017 4
4. TOUCHE-À-TOUT Dév backend, frontend, Machine Learning, UX, Discovery, DDD, Ops, ... 5
5. Co-organisateur du Meetup Cra ing DataScience #abonnezVous 6
6. SPEAKER EN CONF Enfin, quand je suis pris :d 7
7. The Tech Away ( ) #AbonnezVous-bis 8
8. J'ai rédigé sur le sujet du jour un article de blog 9
9. Vous voulez écrire moins de doc ? Une documentation toujours à jour et quasiment sans effort, ça vous intéresse ? Vous en avez marre de vous demander si votre doc est à jour/fiable ? Alors peut-être que ce talk va vous servir 10
10. POURQUOI JE VOUS PARLE DE DOC 12
12. 1. Histoires d'horreur && réflexions sur la doc 2. De la théorie sur la documentation 3. De la théorie sur la Living Documentation 4. Comment j'en fais tous les jours depuis 2020 14
13. IL ÉTAIT UNE FOIS… UNE PLATEFORME “SMART CITY” BY 15
14. CE QUE LES UTILISATEURS VOYAIENT 16
15. CE QU'ILS NE VOYAIENT PAS 17
16. C'est ma 1ère mission ops Et je suis perdu 18
17. UN GRAND SAGE A DIT Sur un projet, on peut obtenir de la connaissance via : les gens, la doc, et le code -- CTH 2024 19
18. LES GENS ? L’équipe ops (client) ne m'onboarde pas Des ops peu enclin à collaborer Le pair-programming est une perte de temps, j’irai plus vite seul 20
19. LA DOC ? Pas de schéma d’archi depuis le cadrage projet On a 7 environnements AWS, personne ne sait me dire quel env sert à quoi Wiki d’entreprise trop déstructuré, pas à jour 21
21. LE CODE ? Le code d'infra est dense : + de 100k lignes de code YAML CloudFormation Il y a plusieurs repos ops, je n’arrive pas à me repérer 23
22. Fichiers markdown disséminés dans le repo Commandes aws cli sans contexte et qui ne marchent pas (ou plus) aws cloudformation create-stack \ --stack-name production-web-app \ --template-body file://infrastructure/cloudformation/templ --parameters \ ParameterKey=EnvironmentName,ParameterValue=Production ParameterKey=InstanceType,ParameterValue=t3.large \ ParameterKey=VpcId,ParameterValue=vpc-0a1b2c3d4e5f6g7h ParameterKey=SubnetIds,ParameterValue=\"subnet-0123456 ParameterKey=KeyPairName,ParameterValue=prod-web-keypa --capabilities CAPABILITY_IAM \ --tags Key=Project,Value=WebApp Key=Environment,Value=Prod aws cloudformation update-stack \ --stack-name production-web-app \ 24
23. DES CHIFFRES & DES LETTRES Deployment frequency 100 jours Dernier redémarrage des VMs 9 mois Autonomie pour faire 1 US 4 mois 25
24. NE VOUS ENFUYEZ PAS TOUT DE SUITE C'est une histoire qui se termine bien, les héros ne meurent pas à la fin Deployment frequency 3-4 jours Dernier redémarrage des EC2 Nightly 26
25. Est-ce que j'aurais pu être autonome sur ce projet + rapidement 27
26. Source: Bottleneck of Scaleups #06: Onboarding 28
30. A mon échelle, j'ai fais du mieux que j'ai pu C'est la faute à la documentation ! ou du moins l'absence de doc 30
32. LES PROBLÈMES AVEC LA DOC "TRADITIONNELLE" 33
33. En lisant les premières pages du livre, je commence à percevoir la documentation sous un angle différent 34
34. #BrainDump #ChecklistDe200Items 35
35. PLUSIEURS SOURCES DE VÉRITÉ 36
36. PLUSIEURS SOURCES DE VÉRITÉ 36
37. PLUSIEURS SOURCES DE VÉRITÉ 36
38. Documentation morte C’est de la documentation considérée comme obsolète à partir du moment où le crayon qui a servi à la rédiger est posé 37
39. UN PEU DE THÉORIE SUR LA DOCUMENTATION 39
40. C'EST QUOI "DE LA DOCUMENTATION ?" Documentation The process of transferring valuable knowledge to other people now and also to people in the future. 40
41. Transférer des connaissances d’un individu à un autre, pour autrui ou pour soi-même, pour maintenant ou pour plus tard 41
42. #thereIsABetterWay La documentation, ce n'est pas nécessairement prendre sa plus belle plume pour rédiger un document avec de la connaissance dedans 42
43. Alistair Cockburn 43
44. Alistair Cockburn 43
45. Alistair Cockburn 43
46. Alistair Cockburn 43
47. Alistair Cockburn 43
48. De la documentation, en vrac discuter au tableau blanc, physique ou numérique pratiquer le pair-programming, le so ware teaming pratiquer la revue de code échanger en async via issues ou discussions/forums ... 44
49. Documenter un processus avec des outils comme (by Atlassian) Loom 45
51. Tip: faire un event-storming tous ensemble à chaque arrivée d'un membre dans l'équipe 47
52. Les discussions en tête-à-tête et la culture orale, ça ne scale pas C'est souvent pour ça qu'on s'appuie sur des documents 48
53. LA DOCUMENTATION VIVANTE, MAIS KESSKECÉDONC ? 50
54. LES PROMESSES Inspirations assumées du Behavior-Driven Development et du Domain-Driven Design 51
55. Evergreen content Evergreen content is content that remains useful without change for a long time 52
56. Le livre propose des patterns pour en construire : Rethinking documentation Knowledge exploitation Knowledge augmentation Knowledge curation Automating documentation Runtime documentation Refactorable documentation Stable documentation How to Avoid Traditional Documentation Living Design Living Architecture Documenting Legacy Applications 53
57. QUELQUES TECHNIQUES CLEFS DE LIVING DOCUMENTATION Celles que j'utilise souvent 54
58. READY-MADE DOCUMENTATION Most of what you do is already documented in the literature 55
59. EXECUTABLE DOCUMENTATION Rendre les éléments de documentation exécutables Générer de la doc à jour à tout moment Evaluer la valeur de vérité des documents 56
60. SINGLE SOURCE PUBLISHING > Convenir d'une (1) unique source de vérité et d'autorité > Si cette donnée doit être mise à disposition d'une audience qui ne peut pas y accéder publier un document construit à partir de cette source de vérité 57
61. KNOWLEDGE AUGMENTATION Techniques pour générer de façon vivante et structurée de la documentation, sans commentaire, à l'aide d'annotations, quand le code ne suffit pas 58
62. @Deprecated(since = "2024.9.21", forRemoval = true) public int ComputeBonus(Atelier atelier) { return ... } 59
63. KNOWLEDGE AUGMENTATION Le code est une carte, Il ne tient qu'à vous d'en être les guides touristiques In a city you have never visited before, you can explore randomly, hoping to bump into something interesting. It is easier to quickly discover the best of a new place with a guided tour or a sightseeing map. 60
64. ASSEZ PARLÉ Un peu de pratique 62
65. MAKEFILE AUTO-DOCUMENTÉ POUR DOCUMENTER DES USAGES 63
66. .DEFAULT_GOAL: help .PHONY: help ## to display this prompts. This will list all help: { echo " Use \`make <target>' where <target> is one of " grep -E '^\.PHONY: [a-zA-Z0-9_-]+ .*?##' $(MAKEFILE_LIST) awk 'BEGIN {FS = "(: |##)"}; {printf "\033[36m%-30s\033 echo "Tips " echo " - use tab for auto-completion" echo " - use the dry run option '-n' to show what make is } | tee /dev/tty | freeze -c full -o docs/available-comman 64
67. $> make || make help; make (>v4), en bonus: charmbracelet/freeze 65
68. DOCUMENTER LE FONCTIONNEL $> make functional-doc; 66
69. Executable documentation : je peux voir ce que le système est censé faire ET si la version du code que j'utilise le fait (ou non) Cucumber, Behave, Specflow+LivingDoc 67
70. Executable documentation : je peux voir ce que le système est censé faire ET si la version du code que j'utilise le fait (ou non) Cucumber, Behave, Specflow+LivingDoc 67
71. Executable documentation : je peux voir ce que le système est censé faire ET si la version du code que j'utilise le fait (ou non) Cucumber, Behave, Specflow+LivingDoc 67
72. DOCUMENTER SON API REST $> make api-docs; (go to ) #ExecutableDocumentation #SingleSourcePublishing : doc HTML produite à partir du code /swagger 68
73. DOCUMENTER SON SCHÉMA DE BDD $> make database-docs; 69
75. DOCUMENTER SON GLOSSAIRE DE DONNÉES $> make business-glossary; 71
76. @Glossary class CatActivity: """The set of the main activities of a cat""" pass @Glossary class Sleeping(CatActivity): """The cat is sleeping with its two eyes closed""" pass @Glossary class Eating(CatActivity): """The cat is eating, or very close to the dish""" 72
77. def Glossary(func): """To decorate a class that models a business concept. Its return func 73
78. Pseudo-algo Parser l'arbre syntaxique du code Si le noeud est une classe Si la classe est décorée @Glossary Récupérer la documentation de ce terme Mettre en forme les termes 74
79. Single-source publishing Le code est la source de vérité qui fait autorité Génération de docs à partir de cette source Docs & source évoluent au même rythme 75
80. DOCUMENTER DES DATA CONTRACTS $> make data-contracts-docs; 76
82. Comment définir des centaines de contrat d'interface ... ... sur le contenu attendu dans un fichier CSV ? (sachant que l'OpenAPI du CSV n'existe pas :) ) 78
83. TL;DR: on a fait du single-source publishing 79
84. CE QU'ON MAINTIENT 80
85. Ce qu'on affiche aux partenaires externes JsonSchemaForHumans, Pydantic, GreatExpectations 81
86. CRÉER DU LIANT AVEC TOUT ÇA 83
87. On a créé plein d'artéfacts de documentation unitaires, comment on peut donner du sens à tout ça ? 84
88. CRÉER UN INDEX, AVEC CETTE UNE ASTUCE SIMPLE 85
89. CRÉER UN INDEX, AVEC CETTE UNE ASTUCE SIMPLE $> tree -H ... Permet de générer une arborescence de fichiers/dossiers du filesystem en HTML 86
90. GÉNÉRER LA DOC DANS VOS PIPELINES CI/CD 1. $> make all-the-docs; 2. $> make deploy-docs; 1. Blob Azure, S3, Gitlab Pages, ... 3. ??? 4. Profit ! 87
91. TOUT ASSEMBLER DANS 1 DOC Tip De l'inspiration à aller chercher du côté du de Simon Brown ? So ware Guidebook 88
96. Individuals and interactions over processes and tools Faire de la documentation, ce n'est pas nécessairement prendre sa plus belle plume pour rédiger un doc avec de la connaissance dedans 95
97. #Evergreen #Reliable #LowEffort #Collaborative #Insightful La documentation vivante, c'est de la documentation qui arrive à évoluer au même rythme que le sujet documenté 96
98. Ready-made documentation Executable documentation Single-source publishing Knowledge augmentation Il y a des patterns qui permettent d'en produire, souvent au prix (d'un peu) d'automatisation 97
99. Par exemple, quand on rédige des décisions d'architectures ADR Il y a des cas où la documentation doit être rédigée avec nos petits doigts 98
101. Des Questions ? 101