Meetup Tech.Rocks : les enjeux de la documentation technique

Comment se manage la production de documentations techniques ? Coley Woyak et Daniele Procida, ont partagé à ce propos leur expérience lors du meetup Tech.Rocks du 10 septembre 2020. Replay.

Speakers, who’s who :

- Daniele Procida est chief collaboration officer chez Divio. Il est à l’origine d’un framework qui facilite la structuration des documents techniques.

- Coley Woyak est tech writer chez Saagie. Elle y a mis en place un système Docs As Code pertinent.

Ce meetup a été animé par Cyrille Martraire, CTO d’Arolla et auteur du livre Living Documentation.

Quels sont les ingrédients d’une documentation technique gagnante ?

Daniele Procida : "Pour moi, une documentation technique doit être tout l’inverse d’un monolithe. Pour être complète, elle doit se composer de quatre éléments bien distincts, à savoir les tutoriels, les guides « comment faire », les guides d’explications et les guides de références. Chaque format doit répondre à un besoin spécifique et suppose une écriture adaptée. Et le mieux est qu’ils soient vraiment séparés les uns des autres. C’est, selon moi, la clé pour rendre leur accès et leur lisibilité efficaces."

En quoi un rédacteur technique a-t-il une valeur ajoutée ?

Coley Woyak : Le profil du tech writer est semblable à celui du bibliothécaire ou du documentaliste. Il sait où trouver les informations sans pour autant être un expert de tous les domaines. C’est une personne connectée, au sens où elle communique régulièrement avec les équipes. Elle collecte toutes les informations du produit ou de l’entreprise. Elle manage l’ensemble du contenu. Elle s’assure de le présenter de façon claire pour le client.

Illustrations par Tommy Dessine

Une documentation, 4 formats, comment appréhende-t-on ces déclinaisons ?

Daniele Procida : "Les tutoriels, pour commencer, sont souvent la partie de la documentation la plus difficile à créer et la plus mal comprise. En réalité, ce sont des expériences pédagogiques où l’on prend par la main le lecteur. On l’amène à réaliser un projet grâce à une série d’étapes. L’intention est identique au fait d’apprendre la cuisine à un enfant. Le ton doit être direct, concret et instiller la confiance. Il faut absolument éviter l’abstrait, les explications ou encore les choix pour éviter de polluer la démonstration.

Illustrations par Tommy Dessine

Autres formats, les how-to, les guides « comment faire » visent à permettre aux lecteurs de concrétiser une tâche en particulier. Ils ont une utilité très pratique. Contrairement aux tutoriels, les how-to s’adressent à des personnes dotées d'un certain niveau de compétences. Durant leur rédaction, on privilégie l’emploi de l’impératif. On répond à des questions avec une série d’actions « faites ceci, faites cela » sans aucune tentative d’enseignement. On évite les digressions ou même les explications.

Quant aux guides de références, ils décrivent purement la machinerie, sa structure et son fonctionnement. Leur style est comparable à des articles d’encyclopédies. Ils informent de la façon la plus complète et correcte que possible. Durant la rédaction, on veille à rester neutre, factuel et objectif.

Enfin, les guides d’explications s’envisagent comme une discussion. Ils amènent un éclairage sur un sujet, comme on le fait dans les domaines des arts, de la science ou de l’histoire. Ils partagent une vision. Ils invitent à prendre de la hauteur, à sortir du périmètre technique pur. On va davantage explorer le passé, le futur et contextualiser. Leur style est toujours discursif."

Comment on applique ça dans la pratique ?

Coley Woyak : "On a mis en place, chez Saagie, un processus de production basé sur quatre étapes. La première, essentielle, fait appel à la contribution des développeurs. Ils draftent eux-mêmes des bouts de documentation concernant leurs travaux. Deuxième étape, j’entre en scène. La collaboration avec les développeurs est alors étroite. On passe du temps à trouver les bons mots, les bonnes tournures pour expliquer les choses. C’est très fructueux. Ensuite, la matière obtenue est partagée avec d'autres développeurs pour validation. Et enfin, les éléments reviennent vers moi lors d’une quatrième étape, où je fais mes derniers commentaires et je valide. On expérimente ce processus depuis plusieurs mois. Parfois, on doit l’implémenter en fonction de projets. Ça marche très bien."

Illustrations par Tommy Dessine

À quoi doit-on être vigilant pour que ça marche ?

Coley Woyak : "Il s’agit d’une part d’avoir une personne responsable du projet, de prioriser d’utiliser de bons outils. Ceci étant, l’adhésion des développeurs est essentielle. Ce sont eux les experts des produits. Ils les comprennent, connaissent leur fonctionnement mieux que personne. Sans eux, ce que nous produisons chez Saagie ne pourrait pas être aussi complet.

Pour obtenir cette adhésion, l’idéal est d’expliquer combien la documentation technique rend la tâche plus simple à tout le monde. Combien elle est utile aussi bien au niveau des clients, mais aussi à celui de toutes les équipes de l’entreprise, les nouvelles recrues notamment."

Des suggestions d’outils utiles à la rédaction de documentation technique ?

Coley Woyak : "Il en existe beaucoup. Des choses comme ReStructuredText, Sphinx, ReadTheDocs.

Il faut les essayer. Il y a, en outre, plusieurs méthodes pour gérer les contenus. Parmi celles-ci, on peut évoquer des systèmes que l’on connaît depuis longtemps, les wysiwyg par exemple. Ils permettent de manager du contenu directement dans les fenêtres de Google Chrome.

En ce qui me concerne, j’utilise le système Docs As Code. Il est particulièrement adapté quand les contributeurs ont des profils techniques. Ça a aussi l’avantage de favoriser l’adhésion des développeurs."

La doc fait-elle partie de vos definitions of done ?

Coley Woyak : "La documentation est incorporée à la définition de “done” chez Saagie. Une “story” n’est pas complète si la documentation n’est pas complète."

Daniele Procida : "Idem chez Divio. La documentation est une partie essentielle du produit. La complexité de notre système est telle que pour l’utiliser, il est nécessaire d’avoir du matériel entre les mains. Il ne peut pas être découvert seulement par l’exploration."

Illustrations par Tommy Dessine

Un grand merci à Coley, Daniele et Cyrille. Le prochain meetup Tech.Rocks, jeudi 17 septembre 2020 aborde la gestion des pics de charge. Nouvel horaire : 12h ! Inscrivez-vous dès maintenant : https://www.meetup.com/fr-FR/Meetup-CTO-Tech-Rocks/events/273132906/

Tous Les Articles
×

Vous y êtes presque...

Nous venons de vous envoyer un e-mail. Veuillez cliquer sur le lien contenu dans l'e-mail pour confirmer votre abonnement !

OK