1 of 24

Une documentation autant qu’un logiciel opérationnel

Ando NARY

@andonary sur X, Mastodon, GitHub, LinkedIn, …

2 of 24

RTFM

3 of 24

Merci de votre attention

Des questions?

4 of 24

Avant l’agilité

5 of 24

Depuis l’agilité

6 of 24

Depuis l’agilité

7 of 24

L’artisanat logiciel

8 of 24

Une documentation au plus tôt

Où se trouve l’information?

  • dans la tête du développeur
  • dans la tête du tech lead
  • dans la tête du product owner
  • dans la tête de [nom de la personne qui n’est pas là]
  • dans la discussion informelle dans laquelle vous n’y étiez pas

9 of 24

Une documentation au plus tôt

​

Comment retrouver l’information?

  • synchrone: posez une réunion avec les personnes sachante
    • l’inviter à une session d’Ensemble Programming
    • l’inviter à une session de Pair Programming
    • message dans le chat
  • asynchrone: lire la trace écrite potentiellement la plus à jour
    • e-mail
    • compte rendu
    • ticket Jira
    • changelog du produit
    • description du commit
    • pavé de commentaire
    • … ou autre

10 of 24

Une documentation au plus tôt

​

Comment retrouver l’information? Une solution efficace…

la combinaison de ces deux systèmes:

  • Chaque point synchrone devrait générer un point asynchrone
  • Pair avec [nom de la personne]
  • Inclure dans le Pair une des traces écrites dans une seule source
    1. Dans la documentation si elle existe, si non pensez affordance
    2. Dans les rituels habituels si trace écrite

11 of 24

Une documentation au plus tôt

​

Clé 1:

En l’absence d’une documentation, c’est l’écrire au fur et à mesure.

Communiquer sur sa présence.

12 of 24

Quoi mettre dans la documentation

Qu’est-ce que je cherche à savoir?

  • Pourquoi est-ce qu’on fait [nom de la bizarrerie] à cet endroit?
  • À quoi sert de faire [nom de la bizarrerie] à cet endroit?
  • Ce ne serait pas plus simple d’utiliser [outils B] au lieu de [outils A]?
  • Comment est-ce que je peux commencer à faire [fonctionnalité A]?

13 of 24

Quoi mettre dans la documentation - ADR

​

https://github.com/joelparkerhenderson/architecture-decision-record

14 of 24

Quoi mettre dans la documentation - ADR

​

  1. Context
  2. Decision
  3. Justification
  4. Consequences

15 of 24

Quoi mettre dans la documentation - ADR

​

  • Besoin
    1. pourquoi on doit faire ce choix
    2. lien ticket Jira OK
  • Contexte
    • l’état actuel de l’organisation
      1. compétences et forces en présences
  • Alternatives
    • lister les autres options possible
  • Qui
    • les personnes qui savent
    • les personnes qui ont participé à cette documentation
    • préciser leur rôle (Développeur, expert métier, etc) et la date d’approbation

16 of 24

Quoi mettre dans la documentation - C4 model

17 of 24

Quoi mettre dans la documentation - C4 model

​

Level 1 - Context

18 of 24

Quoi mettre dans la documentation - C4 model

​

Level 2 - Container

19 of 24

Quoi mettre dans la documentation - C4 model

​

Level 3 - Component

20 of 24

Quoi mettre dans la documentation - C4 model

​

Level 4 - Code

21 of 24

Quoi mettre dans la documentation - C4 model

22 of 24

Quoi mettre dans la documentation

​

​

Clé 2:

C’est chiant d’écrire une documentation exhaustive, � potentiellement apporte peu de valeur si trop long

Allez au plus simple, quelques lignes. Un schéma.

23 of 24

RTFM

24 of 24

Merci de votre attention

Des questions?