Vous êtes développeur ou développeuse PHP : vous aimez programmer, réfléchir. Vous aimez créer des applications ou des bibliothèques de qualité. Mais pourquoi personne ne les utilise ? Parce que votre documentation n'est pas à la hauteur !
Justement : je suis Technical Writer et mon métier est de vous aider à valoriser votre logiciel auprès de ses utilisateurs et utilisatrices, à travers une bonne doc. Comprenons comment architecturer, concevoir et rédiger votre contenu. Découvrons les outils qui vous procurerons une aide précieuse. Enfin, facilitons sa mise à jour pour qu'elle soit pérenne.
Dorénavant, vous saurez identifier les passages obligés et ceux où vous pouvez gagner du temps.
_ Bonjour à toutes et à tous. Je suis venue vous parler de documentation. J'ai un mini jeu, il y a une image et vous me direz à la fin si vous savez quel est l'objet représenté sur cette image. À la fin. Retenez votre impulsivité, s'il vous plaît. Sapristi ! Ça ne fonctionne pas. Je réessaye. Le système me dit qu'il reçoit l'information. Je ne sais pas si je dois faire quelque chose de spécial. Très bien. Je vais aller à mon ordi et vous dire que l'on va parler ensemble de ce programme. Architecturer la documentation, l'organiser. Je suppose que vous en avez déjà une. Vous avez déjà un peu de doc, voire beaucoup. Écrire la documentation, produire le contenu, et une fois que l'on aura vu ces deux étapes, d'améliorer, si on peut encore, les choses.
Une collègue à qui j'ai présenté notre documentation technique et notre système m'a dit : "Oh là là, cette présentation, c'est intéressant. La documentation, c'est quand même chiant." J'espère que vous aurez le même avis qu'elle. J'ai partagé mes slides en PDF sur JoinedIn si vous le voulez. Je vais retenter ma chance. Toujours pas.
Je voudrais que l'on parle du mythe du code autodocumenté. C'est un mythe. Non, le code ne s'autodocumente pas. Certains me disent qu'ils ne mettent pas de commentaire parce que ça a été dur à écrire et il faut que ce soit dur à lire. Ou alors "c'est très explicite, je n'ai pas besoin de commentaire". D'autres disent qu'il y a des commentaires dans le code qu'il n'y a pas besoin de documentation.
Les deux points de vue sont bof selon moi. Ma question est : pourquoi documenter le code ? Pour qui ? Et est-ce que vous ne voulez pas plutôt documenter votre logiciel ? Sur mon image, on a des lignes 3 et 8, les commentaires de codes qui ne servent à rien. Il ne faut pas le faire non plus. On va parler de documentation, vous n'êtes peut-être pas tout ce développeur et développeuse, mais un logiciel, dans mon esprit, ça va de la petite librairie au logiciel packagé pour faire votre site e-commerce. Il n'y a pas de différence sur l'attention que vous devez y porter entre les deux.
Quoi qu'il en soit, les développeurs sont contents. Ils font des logiciels, ils délivrent et pensent que tout va bien se passer. Que les gens vont installer et utiliser le logiciel, comme on installe Firefox. Je fais ma petite randonnée. Les utilisateurs ne savent même pas que le logiciel existe, potentiellement. Ou alors, à quel problème il répond. Si vous en avez la possibilité, une des deux choses les plus difficiles en informatique est le nommage. Il faut se rappeler de bien nommer vos logiciels. Un logiciel qui s'appelle Bref, par exemple, ce n'est pas forcément descriptif de ce que fait le logiciel. Si vous en avez les moyens, il faut prêter attention déjà au nommage.
Quand les gens l'installent, ce n'est pas aussi simple que vous ne le pensez. Soit ils vont le télécharger et lancer le wizard soit ils ont acheté le CD qu'ils vont recevoir par la poste, soit après 1999, ils vont créer un compte sur un outil avec une durée limitée et des fonctionnalités limitées pour tester le logiciel. Dans tous les cas, vos utilisateurs et utilisatrices voudront être accompagnés pour la première étape, éventuellement des prérequis ou un getting started. Les développeurs se disent qu'il y aura peut-être des problèmes, des soucis, des dysfonctionnements. Les utilisateurs vont ouvrir des issues dans Github ou nous envoyer un e-mail. Tout va bien se passer. Je rappelle que plus il y a de codes et plus il y a de bugs : c'est automatique. Il y aura forcément plus de bugs. Quand vos utilisateurs et utilisatrices rencontrent des bugs, ils vont abandonner. Ils vont se plaindre sur Twitter ou ils vont faire les deux.
Face à ces constats négatifs ou déprimants pour certains d'entre vous, je vous propose de penser quand vous devenez utilisateurs et utilisatrices de logiciels, qu'attendez-vous de la documentation ? C'est le sujet de ma présentation. Il faut se mettre à la place des gens qui cherchent votre doc. Ça se passera mieux pour vous. Je vais me représenter, même si on n'arrête pas de me présenter depuis tout à l'heure. J'ai été développeuse PHP dans des temps immémoriaux. Ensuite, j'ai été Technical Writer. J'écrivais la documentation et aujourd'hui, je suis Documentation Architect chez Bedrock. On est nombreux au forum. J'aime les Monty Python, j'ai mangé de la pizza, j'aime faire du vélo et j'aime apprendre beaucoup de nouvelles choses. Je suis trop souvent sur Twitter. Et je remercie mon collègue Tom qui m'a généré cette image. Il y aura peut-être la vidéo plus tard.
Je voudrais parler d'architecturer d'abord. J'estime que vous avez déjà de la documentation. On va la remplir. Vos utilisateurs et vos utilisatrices lisent la documentation, mais pas comment roman de A à Z. Moi qui adore la doc, j'en lis tout le temps pour examiner et je ne lis jamais toute la documentation de A à Z. Il n'y a pas de suspense et il ne devrait pas y en avoir. Vos utilisateurs et utilisatrices lisent la documentation avec un but.
Une chose importante, c'est le contexte, la situation dans laquelle sont les gens quand ils lisent la documentation. "Cette librairie apporte quelque chose pour l'authentification."
Ou alors, ils sont d'astreinte, ils sont un peu plus dans l'urgence, leur data Center est en feu, c'est arrivé chez OVH. Ça peut arriver. Leurs besoins métiers sont différents. Ils explorent. Ils veulent ajouter une feature ou baser leur logiciel sur votre frameworks. Leur besoin peut être plus ou moins important. Le contexte vous aidera pour ranger votre documentation.
Petit point, qu'est-ce que je mets dans la doc ? Des commentaires de code peuvent être un peu dans la doc, mais on a dit qu'on en parlait plus, ça ne suffit pas. En plus des guides que vous avez déjà, et la référence API que vous connaissez bien, j'inclus aussi dans la doc tous les readme qui sont dans vos repo Git ou autre chose, les tuto. Le getting fait partie du tutoriel. Et ensuite, les release notes qui font aussi partie de la réglementation. Vous allez devoir augmenter et orienter votre utilisateur dans la doc. Il y a plusieurs façons de le faire. Je tanne mes collègues avec l'organisation et l'architecture par type de contenu. je vous en reparle juste après avec un Framework qui s'appelle Diataxis, pour la doc, c'est un guide. Vous pourriez vouloir l'organiser par contexte.
Data Center en feu, la doc si tu fais juste de l'exploration relaxes... Vous pourriez l'organiser par feature. Imaginons que vous ayez une appli qui envoie des SMS. Le feature pourrait être le SMS régulier. Votre banque qui vous donne le solde de votre compte. Le SMS auquel il faut répondre pour gagner un tour de cou, le SMS publicitaire qui a peut-être un cadre légal différent. Donc ça va être différent avec différentes features.
Vous pourriez l'organiser par ordre alphabétique. Je ne recommande pas cette organisation, mais pourquoi pas. Et je propose plutôt par type de contenu. On va y passer un peu plus de temps. J'avais un pointeur laser. Il marche !
J'ai mis diataxis.fr, l'image est issue du site Web. Ça donne même des amorces de contenus, mais je voudrais détailler. L'intérêt de ce framework et pourquoi je l'utilise et pourquoi je le recommande, c'est qu'il y a quatre types de contenus. À chaque fois que vous allez prendre un contenu, vous allez pouvoir le ranger dans un des quatre types. Ça fonctionne.
Je commence par le plus simple à expliquer, celui qui est en bas à droite. La référence. Vous connaissez la référence d'API. Ce qui est écrit en range, c'est le but de la catégorie. Information oriented, c'est un catalogue d'informations pour s'en servir.
À gauche, j'ai appelé ça le guide tout à l'heure, ce sera les fonctionnalités. En orange, il y a marqué understanding oriented, c'est là que vous allez expliquer vos fonctionnalités. Vous allez pouvoir mettre du contexte sur vos fonctionnalités et dire pourquoi vous avez fait des choix. Éventuellement l'historique du logiciel.
Les deux catégories sont dans la partie contenus théoriques. Si vous arrivez à lire. Ensuite, en haut, vous avez les tutos. Orange, il est écrit learning oriented. C'est un guide sur par exemple la pagination des contenus que j'ai reçus via l'API. Je guide de A à Z en expliquant tout.
Et de l'autre côté, du côté travail, non pas côté étude et apprentissage, on a les how-to guides qui sont orientés task oriented. Ça, c'est plutôt chouette, ça marche bien, d'ailleurs, j'ai essayé de trouver deux exemples. Je n'avais pas envie de vous assommer d'exemples. Quand vous écrirez du code, vous penserez à cette organisation avec quatre contenus. Ici, je suis dans la doc. À gauche, j'ai le menu. On remarque qu'il y a getting started un tuto qui apparaît en décalé parce que c'est le titre originel qui vous permet de monter la première marche. Ici, la référence, même nom, comme c'est un projet open source, il y a également le contribute que vous n'aurez peut-être pas dans votre documentation à vous. Un autre exemple de site Web qui utilise cette organisation pour sa doc, Mozilla Developper Network. En haut, dans le menu, il y a les références, il y a tous les éléments du langage HTML, vous avez aussi une partie guides. Il n'y a pas les deux parties du haut de mon schéma. Ce n'est pas grave. Quand vous allez ranger votre documentation, il y aura peut-être des catégories qui vont rester vides. Ce n'est pas grave. Vous allez sûrement vous apercevoir que c'est la même catégorie qui est vide. Les tutos. Vous allez peut-être en manquer et devoir en écrire. En rangeant, vous allez vous apercevoir des choses qui manquent dans votre documentation. Voici déjà quelque chose que vous pouvez faire en rentrant chez vous. Enfin, au travail.
En plus du contexte, vos utilisateurs et utilisatrices ont besoin de contenus adaptés à leurs besoins, à leur rôle par rapport à votre logiciel. Ça rejoint un peu les persona UX. Qui a un problème à résoudre et pour qui j'ai créé le logiciel ? C'est mon audience. Savoir pour qui j'écris de la documentation, c'est assez intéressant et astucieux de le savoir. Votre audience aura des questions. Qu'est-ce que c'est que le logiciel qui s'appelle Cucumber ? Est-ce que c'est pour la restauration, est-ce que ça va résoudre mon problème ? Combien ça coûte, comment je fais pour l'API, et s'il y a un bug, comment je remonte ?
Un petit point me tient à cœur sur la diversité de l'audience, je sais que plus tard, il y aura les femmes à barbe et l'accessibilité, cependant, j'ai mis "c'est documenté". Tout le monde ne sera pas identique. Pour savoir comment faire passer ça dans votre documentation, je vous recommande un talk de Cory Williamson-Cardneau qui a été donné en 2017. En deux mots, qu'est-ce que ça change ? En termes de documentation, il y a des blagues qui ne vont pas passer.
Par exemple, les blagues que je déteste, c'est "l'API expliqué à ma mère". Comme si ma mère n'était pas capable de comprendre. Je suis parent, et je gère l'API. Il va y avoir des choses sur les moyens financiers. Si votre logiciel est pour du grand public et s'il faut acheter un autre logiciel ou un matériel coûteux en prérequis, ça va peut-être poser des problèmes. Et puis, sur l'âge. J'ai voulu faire des blagues quand j'ai préparé cette conférence, mais on m'a dit que les gens ne comprendraient pas, que j'étais bien trop ancienne et que ça ne marcherait pas. On fait ce que l'on peut.
Et votre site Web de documentation, vos documentations devraient être sur un site Web accessible, dans le terme d'accessibilité Web du terme.
Pour connaître votre audience, pour qui vous écrivez, normalement, c'est des utilisateurs et les utilisatrices de votre logiciel, sinon, allez voir le marketing. Ils essayent de vendre le logiciel pour ces personnes. Allez voir le support, ils ont les personnes au bout du fil, du mail du ticket de support. Si vous en avez dans votre entreprise, les dev rel si votre logiciel s'adresse à des développeurs et des développeuses. Une fois que vous savez votre audience, notez-le. Si vous êtes plusieurs à travailler sur la documentation, cela vous servira plus tard. Je vais boire un coup. Je dis ça pour la régie.
Entre une documentation où on revient une documentation qu'on laisse tomber complètement, la différence, c'est l'expérience utilisateur. On peut même parler de Developer experience, DX. C'est clairement votre cas aussi, vous allez voir une doc, vous êtes confrontés, vous ne revenez pas dessus et vous cherchez ailleurs. Pour architecturer la doc, il faudra tenir compte de l'audience et du contexte. Le type de contenu, ça fonctionne bien. Si vous voulez une organisation plus fine, il faut penser à ce croisement. Pareil pour écrire la documentation. Je vais vous en parler. Autant j'adore la documentation, autant ça n'est pas une fin en soi, c'est un moyen, un outil. On peut tout faire à la main. On peut monter une obligation notice. Est-ce que vous le feriez ? On peut vice... Y en a qui font : "Oui. T'inquiète." Je les inviterai la prochaine fois. On peut aussi viser son tournevis, mais c'est moins pratique.
On va maintenant parler de production de contenus, et même si nous ne sommes plus en 1977 comme cette superbe image, j'aimerais que l'on parle de Stripe. C'est un moyen de paiement que vous pouvez implémenter sur sites Web. Il m'intéresse pour sa documentation, parce que ça m'est arrivé plusieurs fois de me retrouver en entretien d'embauche et que l'on me dit : "On voudrait une documentation super bien pour notre API." La documentation, pour des API, c'est une bonne idée et on nous dit on voudrait qu'elle soit aussi bien que celle de Stripe. Ils ont une particularité. Quand vous êtes connectés, tous vos exemples sont pour vous. Tout est paramétré pour vous. Le code, vous le copiez et collez ça fonctionne. Tout est du sur mesure. J'ai fait une petite recherche sur LinkedIn, et j'ai eu une information bien précise pour savoir combien de gens travaillent sur la doc de Stripe, pour ceux qui ne voient pas bien au fond, il y a 29 résultats. J'ai aussi contacté quelqu'un chez Stripe pour savoir. Il m'a dit qu'ils étaient 35. Il y a du monde qui travaille sur leur doc. Elle est canon et custom. Mais la documentation, ça prend du temps et des moyens. Quand on met le temps et les moyens, on arrive à une qualité de documentation intéressante. Une autre question que je voulais aborder avec vous, je voulais vous parler de ce monsieur. Il écrit tuto et il a modélisé la Developer loop, c'est l'attitude des développeurs face à un blog. Premièrement, le développeur essaye de comprendre le problème, de le qualifier, et les deuxièmes étapes, le développeur cherche une solution existante. On retrouve de la documentation, éventuellement. Il demande à ses collègues. Je ne vais pas vous expliquer votre métier. Ensuite, il prouve que la solution fonctionne et une fois que c'est fait, en quatrième, il publie la solution pour publier le fix. Ce qui m'intéresse, c'est que cet homme a aussi modernisé le writer loop. Ceux qui écrivent la documentation. D'abord, on essaye de comprendre pourquoi on essaye d'obtenir la documentation. En deuxième, le writer va créer un plan pour résoudre le problème et écrire. En troisième, use common design pattern, c'est l'idée d'avoir des techniques d'écriture habituelle qui font de l'économie d'énergie. C'est très économique. Et puis, il écrit le contenu de la documentation. Ce qui m'intéresse, c'est quand on met les deux boucles ensemble. Le design n'est pas très joli. Attention.
À droite, un ensemble bleu pour la writer loop, j'ai remarqué à quel correspondait à ce que cherchent les développeurs dans les tables 2 qui cherchent partout des contenus. Documenter correspond à créer le contenu que le développeur va chercher pour résoudre les bugs, par exemple. Il faut garder les deux en-têtes. Il faut coder dans un processus unifié. Mes slides sont déjà disponibles en PDF si nécessaire. Une question que l'on pose pas mal, c'est le format à utiliser pour la documentation. Je n'ai pas d'autre réponse qui ira à tout le monde dans cette salle. Je vais vous reposer des questions pour vous aider. Ma question principale : Qui va écrire la documentation ? Qui va la mettre à jour ? Vous pourriez avoir le produit qui écrit la partie guide et les features. Vous pourriez avoir les développeurs qui poussent la référence d'API et puis vous allez avoir peut-être l'équipe support et maintenance qui va mettre à jour la documentation. Pour faire votre choix, il va alors prendre en compte tous les acteurs. Vous allez peut-être avoir des outils différents qui se parlent et qui génèrent la doc. Je n'ai pas la réponse pour vous. Je travaille déjà chez Bedrock pour trouver des réponses pour nous. C'est une question que je me pose souvent.
En parlant d'écriture, écrire une page de doc, comment on fait ? Après tout, on peut revenir aux bases et au début. Ce n'est jamais perdu. Je vous conseille de vous intéresser à votre audience : pour qui vous écrivez ? Quel type de contenu vous allez faire ? Et vous vous demandez quel est le but de votre page. Vous allez trouver un titre. J'ai des administrateurs systèmes et réseaux. Je veux faire un tuto pour expliquer comment installer. Je vais créer une page et l'appeler tuto d'installation. Je veux préciser. Des fois, il y a null et parfois, il y a false. Je vais préciser un petit peu. Ça, c'est un premier pas pour écrire la documentation. Si jamais, vos titres coincent un peu, je vous conseille d'écrire un court tweet, pas de le publier, mais d'abord écrire une phrase courte et après, étoffer. Si vous ne savez pas par où commencer, j'ai une autre idée pour vous. Vous changez de médias. Vous pouvez utiliser du papier. Oui, je sais, c'est surprenant et old school ou votre tableau blanc que vous avez à disposition dans votre bureau quelque part. Vous pouvez en parler avec vos collègues. Vous mettez éventuellement un petit enregistreur pour récolter vos idées. Vous pouvez utiliser des templates. Vous avez le droit de reprendre des documentations et de reprendre la même structure. Ce n'est pas un roman de fiction avec une intrigue palpitante. C'est plutôt des fiches comme des recettes de cuisine. Si la structure est toujours la même, pas de problème. Ça n'est pas un problème.
Je fais beaucoup de marche !
Une fois que vous avez écrit du contenu textuel, vous allez vouloir ajouter des images. Donc oui, faites attention à l'accessibilité, mais vous êtes des professionnels. Je ne vais pas vous apprendre tout ça. J'ai listé trois types de contenus. Les icônes. J'ai mis un screenshot d'une documentation que l'on m'a recommandée comme documentation agréable à lire et à parcourir. Elle n'a pas tellement d'images à part les icônes des chapitres. On voit une école pour le sommaire. On voit une icône sur la petite horloge. Très bien. Les schémas aussi. Vous allez vouloir en rajouter. Et des copies d'écran.
Pour les schémas, je suis pour ! Les schémas permettent de décrire quelque chose d'intangible, vous pouvez faire des schémas de détails d'interaction plus beaux que mes loops des schémas beaucoup plus larges qui décrivent un système complet ou les deux. Le schéma large et des zooms. J'ai trouvé sur la page d'accueil de la documentation ici un schéma, il décrit le rapport entre le container, le registry, etc. On peut faire un texte pour le décrire et le schéma rajoute une information. On l'appréhende encore mieux. Les schémas, c'est oui. Soit c'est un camion qui recule, soit le bâtiment est en feu. Nous le saurons plus tard.
Ensuite, troisième type de contenu, les copies d'écran. Si vous avez une interface utilisateur, vous voudrez certainement en mettre dans votre documentation utilisateur. Je vais trop vite.
Je vous conseille d'utiliser une technique qui a été nommée SUI, l'idée est de rendre des éléments visibles en masquant les autres. J'ai une copie d'écran de la documentation d'user de Slack. C'est pour quitter un canal Slack. Au lieu de nous avoir mis une copie d'écran du bouton, on a remis un peu de contexte. Sauf que le texte a été flouté avec des bandes grises. Cela permet de se dire dans quel genre d'interface il se trouve. C'est du travail ! Ça demande des efforts, mais ça vaut le coup. C'est ce que je vais dire à chaque fois.
Et puis, il y a des documentations où il n'y a pas d'images, mais vous avez quand même une excellente raison d'y revenir parce qu'il y a une très bonne user expérience pour vous. Ça va être toutes les man pages Linux. Il y a le nom de la commande, la liste des options, le détail avec une description de la commande et la liste des options et toute leur valeur. Parfois, c'est un peu différent, mais il y a une très bonne expérience sur ces pages.
Je vous recommande d'utiliser les moyens disponibles. Par exemple les notes, les warnings. Il ne faut pas en utiliser trop non plus. Là, j'ai pris ça sur la doc Symfony. C'est très sobre. Utilisez du gras. Je ne lis pas de A à Z la doc. Je scanne avec la recherche de contenus en tête.
Si c'est trop long, il faut diviser le contenu. Si c'est trop long pour vous, vos utilisateurs trouveront ça beaucoup trop long. Vous pouvez faire tester la documentation par vos collègues qui l'utiliseront et vous feront des retours. Autre chose que vous voudrez peut-être inclure dans votre documentation si vous faites des logiciels pour les développeurs et les développeuses, c'est du code. Je distingue deux types de codes. Le code exécutable. Vous allez le copier et le coller et il fonctionne.
Le code explicatif, c'est celui que l'on retrouve dans les tutos puisque c'est du code d'explication. Par rapport au code explicatif, si vous le pouvez, il faut mettre plusieurs niveaux de complexité. Les exemples très simples, ce n'est pas forcément ce que l'on cherche.
Les exemples de code, c'est la raison pour laquelle chez Stripe il y a 30 quelques personnes qui travaillent sur la documentation, c'est parce qu'il faut les mettre à jour. Il y a quelques jours, j'ai fait cette copie d'écran. J'aurais dû faire des devinettes pour savoir de quelle documentation s'est étirée. Là, c'est la doc des sessions dans Symfony. On voit des petits commentaires. On se dit que c'est plutôt une doc explicative. Vous pouvez la copier et la coller, mais on s'attend à ce que vous ajoutiez votre commentaire.
Au niveau de l'outillage, il existe la documentation de la documentation. Il y a un site et une conférence attenante qui s'appelle Write The Docs, on vous explique comment, pourquoi faire une documentation. Il y a une liste d'outils très importants. Comme vous êtes des développeurs, je vous invite à faire des ReadMe de qualité pour vous-même dans le futur, vos collègues et tous les autres utilisateurs et utilisatrices de votre code. De ressources. La ReadMe checklist sur Github. C'est une checklist pure et simple. Et Feedmereadmes vous pouvez envoyer votre ReadMe et les gens vont le lire et donner leur avis. C'est plutôt sympa.
Et puis, les outils que j'utilise tous les jours en tant que personne qui fait la documentation, pour le français, une langue qui n'aime pas trop les répétitions, j'ai un dictionnaire des synonymes qui est assez utile. Ça m'a aidé pour jouer à Semantics* si jamais.
Sinon, Linguee. C'est intéressant parce qu'il cherche dans un contexte de publication des traductions. Linguee, c'est pour traduire les expressions qu'il est intéressant.
Un autre outil qui m'a été recommandé par un collègue et que j'utilise depuis lors, c'est LanguageTools. Ce n'est pas grave. Vous êtes nul en orthographe, vous pouvez avoir des amis ou des outils. Il existe pour le français et l'anglais. C'est un concurrent de Grammarly.
Vous pouvez aller sur la page d'accueil et coller votre texte, vous pouvez installer des extensions. Je vous recommande l'outil.
Un autre outil. Avant de vous parler d'outils, je vous explique pourquoi vous en avez besoin. Vous pourriez avoir une documentation [propos en anglais].
C'est un peu trop formel, je ne peux pas scanner cette phrase. Elle est trop longue. Il faut avoir un juste milieu entre le partiel et l'informel.
[Propos en anglais]
L'harmonisation des termes va être un gage de sérieux de votre documentation. Cela rendra la recherche possible dans votre documentation. La qualité de vos documentations sera augmentée. Pour ça, vous avez PSR18 et moi, j'ai le Styleguide de la documentation. C'est un peu le même principe. Je vous recommande Google Developers Styleguide et vous saurez comment on écrit les mots. Il faut mettre des listes de tableaux pour vous parler de fonction, vous aurez réponse là-dedans.
En tout dernier, qu'est-ce que l'on peut améliorer une fois que l'on a rangé et écrit du contenu ? Je vais reboire un peu.
Qu'est-ce qu'on peut améliorer dans la documentation ? C'est un outil qui permet de gagner du temps et d'apprendre des choses. Il y a des attendus. Les gens s'attendent à trouver un certain nombre de trucs vachement cool pour l'UX. Ils s'attendent à savoir dans quelle version ils sont et changer de version. J'ai mis deux exemples. On voit qu'il y a une version future qui n'est pas publiée. On voit qu'ils mettent à dispo une version non publiée. Ou alors, PYTHON. On voit qu'il y a une nouvelle version qui cohabite avec les anciennes. Si on ne vous le propose pas, il faudra peut-être ajouter cette fonctionnalité dans votre doc. À ce propos, si jamais vous avez un produit legacy, il y a un risque que ça nuise à votre UX si jamais la doc legacy à un meilleur SEO que le produit actuel, parce que le contenu est depuis plus longtemps sur Internet. Ça m'est arrivé. C'est pour ça que je mentionne.
De votre côté, vous avez la charge d'avoir la documentation à jour. Vous pouvez afficher la date de mise à jour. Ne affichez pas si jamais elle n'est pas à votre avantage non plus, si c'est mis à jour tous les ans. Peut-être que vous allez devoir réfléchir à votre cycle de release de code. Est-ce que vous mettez la doc à jour en même temps ? C'est l'idéal. C'est à vous de voir.
Et quelque chose de très important, c'est que le futur n'existe pas encore. Donc on ne le documente pas. Je répète, on ne documente pas le futur. Jamais ! Et si vous avez de la documentation périmée, vous la supprimez. Ne la laissez pas sur Internet, ça n'est pas nécessaire du tout.
Et une dernière chose qui est attendue, c'est la recherche. Vous ne lisez toujours pas la doc deux A à Z comme un roman, et même si l'architecture est bien faite pour savoir où on est et permettre de remonter pour repartir dans un autre du tout, mais il y aura un moment où vous aurez peut-être envie de travailler sur le SEO de la doc. Ce n'est pas ma spécialité, mais vous voudrez peut-être ajouter un moteur de recherche. Je vous conseille cela parce qu'on me l'a conseillé.
Pour finir, pour faire une bonne doc, je vous conseille, si vous n'êtes pas doc writer de copier votre doc préférée ou de suivre un guide. Ce que vous aimez, vous le refaites et ça va bien se passer.
Ma conclusion, c'est que la doc est un outil de communication et prendre du temps pour faire la documentation, ça vous le coup. Ça fait une doc de meilleure qualité, mais ça prend du temps, des gens, mais ça vaut vraiment le coup. La doc mérite votre temps. C'est un gain de temps, une aide réelle pour vos utilisateurs et utilisatrices. Elle vous permet de communiquer les choix que vous avez fait dans le développement et de la prendre aux gens via les best pratices.
Merci à vous, et si vous le voulez, vous me direz quelle est l'image.
_ Merci, Sarah. Nous n'avons pas de temps pour des questions, néanmoins, pensez à aller voter pour les talks. Vous avez le petit QR Code qui est là et qui défile sur les slides entre les conférences.
_ Je serai sur le stand Bedrock. Si vous voulez me poser des questions.
Tweets