Cette présentation aborde l'importance de la documentation persistante dans les projets Drupal, en mettant l'accent sur la communication, l'entretien, et les défis associés à la mise à jour de la documentation. Elle propose des stratégies pour planifier, rédiger et évoluer la documentation, ainsi que des conseils sur les types de documentation à utiliser et les outils adaptés. L'accent est mis sur la création de documents clairs et efficaces qui répondent aux besoins de l'équipe tout en favorisant une culture de documentation collaborative.

1. Écrire de la
Documentation
Persistante pour un projet Drupal

2. Matthieu Gadrat
https://drupal.org/u/mgadrat
https://mgadrat.com
@mgadrat

3. Dans cette présentation
Pourquoi?
Qu’est-ce
qui ne marche
pas?
Comment?
Qu’est-ce
qu’on peut y
faire?
Quoi?
La
documentation
persistante

4. Dans cette présentation
● Un guide de rédaction
● La promotion d’un outil de document
● Des gifs amusant ( Par manque de temps )

5. Pourquoi?

6. Pourquoi produire de la doc?
Communiquer :
● Construire la BONNE CHOSE
● Faciliter l'entretien de ce qui a été construit

7. C’est quoi le problème avec la doc?
● Pas à jour?
● Qu’est-ce qui fait partie de la documentation ?
● Qui doit la faire / mettre à jour ?
● Quel niveau de détail ?
● Personne ne la lit !
● Différente de projet en projet !
● Différent documents se contredisent !
● Elle contient des éléments « Out of Scope »

8. Spoiler:
On ne fera pas de miracle ...

9. Comment ?

10. Évaluez l’effort de documentation
● Estimez le temps que vous passerez à produire
○ La documentation fonctionnelle (User stories etc.)
○ La documentation technique
○ Un manuel d’utilisateur / manuel d’installation
○ Maquettes / Wireframes / Workflows
○ Plan de test / Gestion de risques
● Technique d’estimation
○ À la pièce
○ % global du projet

11. Considérez les outils dans Drupal
● Simplifiez vos manuels d’utilisation avec des descriptions de champs clairs
● Construisez des contenus exemples
● Devs, utilisez les (.info.yml) pour expliquer le rôle d’un module et ses
dépendances
● Avez-vous entendu parler du « tour api? »

12. Planifiez la rédaction de documentation
● Maintenant que vous avez des chiffres
● Mettez-le à l'horaire !
● Ne planifiez pas toutes le heures au début du projet

13. Créez une vitrine de projet
● « One Pager » pour « on-boarder » l’équipe
● Doit expliquer
○ Où trouver « quoi »?
○ Comment utiliser la documentation?
○ À qui poser des questions?

14. Décidez QUI rédige
● Chacun son corps de métier
● Lors de la planification, soyez claire sur les livrables et les responsables de
ces livrables.
Évitez de faire rédiger la documentation fonctionnelle par la personne qui va
construire l’outil (le dev).

15. Présentez la documentation
● Ne faites pas juste envoyer la documentation aux destinataires
○ Personne ne va la lire
○ Ceux qui vont la lire ne vont rien retenir
○ Des questions cruciales ne seront pas posées
● Rencontrez-vous pour présenter la documentation !

16. Prévoyez l’évolution de la doc
● Ayez un processus pour permettre l’évolution de la doc qui est:
○ Simple
○ Permet à tout le monde de le faire
○ Permet l’approbation des correctifs rapidement

17. Désignez un concierge
● S'assurer régulièrement que:
○ Les processus sont respectés
○ La documentation est au bon endroit
○ Les meilleurs pratique de l’entreprise sont suivis
○ Les individus font bien le « ménage » derrière eux
● Peut être externe au projet
● S’il a des connaissances techniques peut aussi vérifier que les
« repos » sont en ordre.

18. Quoi ?
( On y arrive finalement, la documentation elle-même )

19. Choisir le type de documentation
● Il y en a des tonnes (stratégique, technique, fonctionnelle, etc.)
● S’entendre au début du projet sur ce qui sera utile
● Prendre conscience de documentations jetables vs persistantes
● 80 / 20 : + de valeur = + doc
● Un document est un livrable en soit, même si c’est pour l’interne
● N’oubliez pas les besoins de votre équipe
Ex: Un dev à besoin de savoir comment installer un projet sur son ordinateur.

20. Exemple de type de documentation
● Arborescence
● Wireframe
● Mockups
● Ui-Kit
● Copy Deck
● Maquettes
● Diagramme de systèmes
d’information
● Workflows (ANSI / UML)
● Requis fonctionnels
● Requis non-fonctionnels
● User Stories
● ...
● User Stories
● Plan de test
● Plan de gestion du risque
● Issues: Todo, bug, feedback
● Manuel d’installation
● Manuel d’utilisation
● Diagramme de DB
● Diagramme de Classes
● Processus de déploiement
● Contacts
● ...
« In App » Drupal
● Aide
● Tooltips
● Description des champs
● Description des modules
● Inscriptions du « Status Page »
● ...

21. Écrivez de la documentation facile à maintenir
● DRY (Do not Repeat Yourself)
● Indiquez clairement ce qui n’est pas utile dans un document
ex: « Ne pas se fier au texte dans cette maquette »
● Favorisez des « bullet point » lorsque c’est possible.
● Ne pas mélanger de la documentation « jetable » avec de la documentation
« persistante »
ex: Une description fonctionnelle et une tâche

22. Parlons des User Stories 1/2
● C’est bon pour
○ Démarrer une conversation
○ Comprendre le contexte d’une fonctionnalité, couvre les besoins
○ Parler du parcours d’un utilisateur
○ Point de départ des plans de test
● C’est moins bon pour
○ Dire à un dev ce qu’il faut construire
○ Requis non-fonctionnel (Sécurité, performance, etc. )
○ Énumérer des choses
Si c’est mal écrit, ça sonne bizarre...

23. Parlons des User Stories 2 / 2
● Oui, c’est juste un phrase, mais voyez la comme un titre
Titre: En tant que « rôle », je peux « action » afin de « but »
Description: Tous les détails de ce que ça implique.
● Utilisez-les pour grouper des spécifications
● N’oubliez pas d’y joindre tous les détails nécessaires pour les devs
● Gardez les titre courts, gardez les détails pour la description

24. Un User Story =
Persistant Jetable
Une tâche

25. Parlons des User Stories 3 / 2
User story:
En tant qu’éditeur je peux rétablir une version antérieure d’un article afin de
corriger une modification accidentelle.
Tâche:
Activer les révisions sur les articles pour les éditeurs.

26. Parlons des User Stories 4 / 2
User story:
En tant qu’éditeur je peux rétablir une version antérieure d’un article afin de
corriger une modification accidentelle.
Tâche (bogue):
Les éditeurs peuvent voir les révisions,
mais il ne peuvent pas les rétablir.

27. Choisir un outil de documentation
● Joue un rôle de « HUB »
● Versionnés
● Statuts
● Commentaires
● Facile à mettre à jour
● Séparer le jetable du persistant
● Faire des liens entre les documents
● Faire des liens vers des outils externes ex: Mockups, invision etc.
● N’est pas WORD

28. En résumé....
● Évaluez et planifiez l’effort et l’évolution de documentation
● Considérez les outils dans Drupal
● Créez une vitrine de projet
● Présentez la documentation
● Favorisez la documentation facile à maintenir
(même si c’est moins beau)
● Faites des choix éclairés
(Type de document, outil de documentation, etc.)

29. Questions ?
https://drupal.org/u/mgadrat
https://mgadrat.com
@mgadrat