Sans documentation, la fonctionnalité n'existe pas !

Bonjour à tous aujourd'hui je suis venue vous parler de vos fonctionnalités bien sûr et dans une conf que j'ai intitulé "No doc no feature" Je me présente : je suis Sarah Haïm-Lubczanski, je twitte beaucoup trop, j'ai été développeuse PHP par le passé, j'ai même fait partie de l'AFUP de façon assez intensive.

J'étais formatrice sur des technologies open source et aujourd'hui je suis technical writer et aussi canard en plastique pour mes collègues développeurs. Est-ce qu'il y en a qui ne savent pas ce que c'est qu'un canard en plastique ? Donc j'explique rapidement : quand il y a un problème vous pouvez l'expliquer à votre canard en plastique et le fait de l'expliquer vous aide à résoudre le problème.

Souvent on me demande quel est mon travail : c'est de répondre à cette question : à quel endroit je mets cette information dans la documentation ? Par exemple le nouveau paramètre d'une fonction : facile, pour celui là. Ou alors un "how to implémenter le facebook connect dans mon histoire de commentaire" ? Un peu plus compliqué.

Donc ça c'est vraiment mon métier et comme on me demande souvent ce que je fais je voulais vous en parler.

Me voilà au travail avec mon collègue voisin de bureau (@voisindebureau sur twitter !), et il me dit : "Pour le projet 42 j'ai besoin de choisir une librairie et j'en ai trouvé 3 qui me conviennent pas mal de prime abord et je voudrais que tu m'aides à choisir". Donc là c'est quand je suis "canard en plastique".

Dans les librairies qu'il m'a présenté il y avait "Doudou Lib", qu'il avait déjà utilisé sur un projet précédent et il n'y a pas vraiment toutes les fonctionnalités requises pour pouvoir faire ce qu'il veut faire pour son projet 42, mais comme il l'a déjà utilisée et qu'il la connaît bien, il peut la hacker, l'étendre - c'est vraiment confortable.

Par contre il n'y a aucune doc qui existe sur cette "Doudou Lib" donc il hésite parce qu'il sait que je suis très sensible à la question de la doc.

Il y a également "Pote Lib" : c'est son pote qui lui a recommandée, il a fait son dernier projet avec, il lui a fait une démo et ça se passe très très bien.

La doc existe - elle est pas d'enfer - mais surtout son pote peut l'aider s'il a besoin, et ça c'est quand même quelque chose de sympa.

Et puis il y a "Shiny Lib" : c'est la toute dernière qui est sortie, il l'a trouvée en faisant une petite recherche via Github sur les projets open source.

"Shiny Lib" on la connaît pas trop puisque il n'y a pas de savoir et d'expérience sur le sujet, le développeur est seul, en Australie, on peut lui poser des questions il est plutôt accessible, par contre vu le décalage horaire on aura la réponse le lendemain ou le surlendemain quand il est disponible - selon la météo peut être.

Et la doc existe et elle a l'air plutôt costaud : il y a carrément un wiki ! Imaginez toutes les informations qu'il va y avoir pour cette librairie. Du coup il m'a demandé de l'aide pour choisir.

Je lui dis : "Ok, je vais t'aider pour choisir". Si vous, vous avez déjà fait votre choix, envoyez "doc" au 6 12 12 pour savoir laquelle on va choisir.

Donc, celle qui a déjà une doc : on va commencer par "Shiny Lib". Forcément, ça m'intéresse et je vais aller voir la doc.

Je vais dire si je la trouve bien, super, extra-géniale ou moyenne.

Et donc, ensemble, j'aimerais qu'on regarde ce qui fait la qualité d'une documentation.

Déjà elle existe - c'est un premier pas - mais qu'est ce qui va faire sa qualité ? Qualité du code, vous connaissez mais qualité de la doc : comment ça marche ? En discutant hier, avec mes collègues speakers, je me suis aperçue que tout le monde ne pensait pas la même chose de la doc. Si vous avez un téléphone mobile je vous propose d'aller sur cette url : Je vais essayer une manip, j'espère que ça va fonctionner.

J'essaye de taper à une main...

Au temps pour moi, vous n'avez plus la doc...

Ok, c'est inversé droite et gauche et pas responsive, ça va être hyper embarrassant ! C'est pas grave, dans ce cas là : nous allons reprendre le cours normal des opérations.

Je suis navrée, je regarderai vos votes plus tard, mais je vais essayer de vous apporter ce que j'estime faire partie de la doc.

Donc les "README" ça fait partie de la doc : il faut les soigner comme les autres. S'il y en a un, c'est déjà gage de qualité.

Donc si vous en avez un : bravo ! Egalement hier, on m'a beaucoup parlé des commentaires de code, on m'a demandé ce que j'en pensais.

La doc générée à partir des commentaires, je la place dans la doc d'API, ça fait partie de la doc.

Les releases notes, dont je m'occupe dans mon entreprise, ça fait partie aussi de la doc puisque ça me donne de l'information sur les features, sur les dates de sorties.

Les best practices : si vous avez un projet open-source auquel vous voulez que les gens collaborent, les bonnes pratiques font également partie de ce que vous documentez.

Et puis il y a ce que vous avez peut-être répondu sur answergarder (que je verrai donc plus tard) : - les tutoriels - la référence - les how to ou les cookbooks - et les guides ou l'explication des concepts. J'ai mis cette slide parce que beaucoup de gens n'étaient pas forcément d'accord avec ma vision, donc au moins là j'espère qu'on parle de la même chose.

C'est bien tout ça, mais comment on mesure vraiment la qualité de la doc ? Comme mon collègue insistait et me dérangeait durant mes activités extrêmement importantes, j'ai dit : "D'accord, je vais te dire ce qui fait la qualité de la doc, pour moi".

Une des choses qui fait une bonne qualité, c'est d'avoir de la cohérence : avoir les mêmes mots dans le texte, les exemples, vos schémas, vos images - ça paraît basique, mais c'est un gage de qualité.

N'oubliez pas que les mots dans le code et les mots de la doc doivent être les mêmes.

Hier, quelqu'un m'a dit qu'il a fait du reverse engineering : il a regardé dans le code pour trouver la bonne page de doc, pour avoir le nom de la fonctionnalité qu'il cherchait ! C'est une manière de trouver la doc mais je ne sais pas si c'est la bonne...

Dans le logiciel, vos messages d'erreur, vos libellés et vos tooltips doivent être cohérents.

J'ai aussi mis en en copie un tweet de quelqu'un qui se plaint d'une doc qui utilise deux façons de décrire les choses et quand il en parle aux personnes qui font la doc, elles répondent qu'en fait, c'est pas du tout ça, c'est encore une troisième façon.

J'ai pris un exemple - j'ai fait des screenshots ne sachant pas si j'aurai du réseau - ici la doc de Docker - vous connaissez je crois, je compte sur vous - pour docker un conteneur signifie quelque chose, un registry autre chose, un client, et donc on voit un schéma où il y a ce vocabulaire - très simple mais c'est déjà ça.

Ensuite, la clarté : au niveau de la navigation (j'englobe l'accessibilité : même si c'est un chapitre à part entière, vous êtes forcément renseignés) et au niveau de l'utilisabilité, je vous renvoie à Opquast (les gens qui font du web depuis longtemps connaissent) qui a fait des listes et des checklists de bonnes pratiques.

Dans la catégorie navigation par exemple : la 148, l'utilisateur est averti des nouvelles ouvertures de fenêtres.

Il y a aussi des choses sur la page d'accueil : revenir à la page d'accueil.

Je vous laisse regarder leurs checklists qui sont assez exhaustives. Donc ça, c'est du web, c'est facile.

Et puis, quelque chose qui fait de la qualité c'est les liens sémantique : c'est-à-dire la recommandation.

"Tu as acheté des chaussettes, peut-être es-tu intéressé pour les chaussures" ou vice versa.

C'est pas forcément automatisable, certains logiciels ou solutions le font mais ce n'est pas forcément facile.

Je vous donne des exemples de doc que normalement vous fréquentez pour vous en inspirer.

La doc Symphony : ici, la page sur les controllers - vous la consultez même plus tellement c'est acquis pour vous. En bas de la page il y a le keep going avec un lien vers les templates, et les petits liens "learn more about controllers" avec des how to sur d'autres sujets en rapport avec les controllers.

C'est plutôt intéressant, et à l'inverse, quand on est dans le how to, avoir un lien vers les autres sujets connexes.

La fiabilité : le fait d'avoir la doc disponible, de savoir que le site ne va pas crasher que la doc sera là, éventuellement pouvoir la télécharger hors ligne, c'est un gage de qualité pour moi.

Les trucs tout bêtes comme savoir quelle version on est en train de consulter (vous pouvez trouver ça bizarre mais il y a des docs qui ne le mentionnent pas), et parfois la date de mise à jour, parce que c'est des anciennes versions avec des mises à jour dessus.

J'ai pris un exemple que vous connaissez tous en terme de doc : vous voyez que pour la fonction "Error get last", on voit la version précisée PHP 5 à partir de 5.2.0.

Pas la peine de chercher avant ou après donc ça c'est plutôt intéressant.

Et puis on passe à la qualité supérieure : la doc est-elle disponible dans ma langue natale ? Coup de bol : la doc de PHP est disponible en 10 langues ! Merci beaucoup aux traducteurs et collaborateurs.

Et ça c'est plutôt intéressant, ça va faciliter ma compréhension.

Et puis la qualité supérieure, c'est aussi d'offrir de l'aide.

Là j'ai mis une copie d'écran de la doc de Django dont la rubrique "get help" renvoie vers la FAQ, la table des matières, la mailing list ou le channel IRC et même le gestionnaire de tickets pour rapporter des bugs parce que ça arrive.

Et la qualité de luxe - alors là on monte encore d'un cran c'est d'avoir des informations vraiment...

Les trucs que les gens vont chercher chercher via Google, par copier-coller du message d'erreur, ou les questions que vous voyez sur Stack Overflow : vous pouvez vous en inspirer pour créer votre doc (si les gens demandent, ce serait bien qu'on les trouve dans les FAQ).

J'ai pris l'exemple de la doc de Stripe, qui est un moyen de paiement, où ils ont mis leurs codes d'erreur.

Ils s'appuient sur les codes d'erreur HTTP mais là par exemple sur la page 400, c'est parce qu'il manque une information, un paramètre.

Ils le re-précisent alors que les codes d'erreur HTTP, c'est quand-même familier.

Et puis, dans la qualité de luxe, il y a les feedback.

Pouvoir donner du feedback sur la doc elle même mais également du feedback sur le produit.

Pouvoir contribuer : comment on fait pour contribuer ? Une doc très bien faite mais pas très jolie, c'est la doc d'Apache.

Personnellement, j'ai toujours trouvé ce que je cherchais dans la doc d'Apache.

Là c'est la page d'aide de la doc d'Apache qui me permet de : résoudre un problème, faire une suggestion, des tas d'autres choses et en dernier, lire la doc, avec des liens afférents qui renvoient à la bonne page.

Et dans la qualité de luxe on a aussi les bugs, erreurs, troubleshooting : des choses que vos utilisateurs vont rencontrer, c'est pas mal de les documenter.

Soit vous préparez une nouvelle version et ce bug vous ne le corrigerez jamais, soit vous y travaillez, mais vous savez pas comment le résoudre, alors vous offrez un contournement.

Je donne des exemples à chaque fois pour vous inspirer : la doc de Twitter propose tout ce que le développeur devrait savoir comme la limite aux calls que vous pouvez faire sur la doc de l'API.

Autre exemple : la doc d'un produit que vous utilisez peut-être, Github.

Sur leur API REST V3, il y a des questions comme "Pourquoi j'ai une erreur 404 alors que mon repo existe ?" Donc ça peut être une idée pour avoir une doc de luxe Alors voisin de bureau, après avoir relu la doc de Shiny Lib, il décide de l'éliminer.

Désolé votre candidat n'a pas gagné. Pourtant c'était celle qui promettait d'avoir le plus de doc et la meilleure.

Mais la doc était vraiment insuffisante pour travailler et comme sur les autres points, il n'était pas sûr d'avoir de l'aide, il a préféré l'éliminer de son choix.

Et puis un autre jour, Voisin de bureau dit à son collègue qu'il a fini un ticket et qu'il va pouvoir en faire un autre.

Et son collègue lui demande s'il a fait la doc au moins en rapport avec sa fonctionnalité.

Il répond "Non, je ne l'ai pas faite, j'espérais vraiment avoir fini, je suis pas content (il dit des mots plus grossier mais je ne répèterai pas !).

Du coup, en quoi ça consiste "faire la doc" ? En fait j'aurais peut-être dû faire des sondages avant pour savoir qui a de la doc sur son produit (je parle ici de doc interne ou de doc de votre logiciel).

Trois étapes assez simples : créer la doc, maintenir la doc et valoriser la doc.

Le but c'est que vous utilisateurs apprennent des choses et résolvent leurs problèmes.

Pour ma doc, il ya trois choses : l'installation, l'utilisation des fonctions de base (installer eZ platform, publier du contenu) et l'utilisation des fonctions avancées (organiser et traduire ce contenu).

Pourquoi écrire la doc ? J'espère que ce slide ne sert à rien du tout ! Parce que franchement je l'ai juste mis pour avoir bonne conscience.

La réponse c'est : pour vous dans le futur, pour vos collaborateurs, partenaires commerciaux, intégrateurs qui intègrent votre solution qu'elle soit pas open source ou pas, pour obtenir des contributeurs (si votre produit est documenté, les gens auront peut-être envie d'aider) et éventuellement - je sais que certains ont écrit et publié des livres avec succès - si vous voulez vous améliorer en écriture, écrivez de la doc.

Est ce qu'il y a ici des gens qui n'ont rien dans leur doc ? peut-être un nouveau projet ? Non ? Mais vous êtes des élèves exemplaires ! Du coup j'ai pas besoin de parler de ça...

Si jamais vous faites un nouveau projet et que vous n'avez rien, commencez avec deux rubriques : installation et utilisation. Vous rangerez vos affaires dans les deux rubriques.

Maintenir la doc : ça c'est un peu mon boulot quotidien.

L'idée c'est de mettre à jour le contenu, y compris supprimer ce qui ne sert plus à rien.

Souvent on oublie de faire et on se retrouve avec des choses obsolètes, deprecated dans la doc.

Utiliser aussi des outils en rapport avec votre besoin. Je travaille dans une société qui fait un CMS open source.

Notre documentation n'est pas faite avec ce CMS open source, ça semble louche à beaucoup de gens, mais vu que le CMS était en cours de développement, les fonctionnalités dont on avait besoin dans la doc, pour faire une doc de qualité comme je vous l'ai montré préalablement, n'étaient pas présentes dans le CMS au moment où on a commencé la doc.

Donc on s'est dit "On va se faire une mauvaise publicité d'utiliser notre produit et de faire une doc appauvrie, sans liens sémantiques ni recherche parce que ce n'est pas encore présent dans le logiciel.

Donc on a choisi une autre solution dont je vais vous parler après.

Les outils : je vais faire une petite passe sur quelques outils et vous expliquer mes préférés.

Alors valoriser la doc j'ai l'impression que c'est la chose qu'on oublie le plus.

Je vous mets un exemple de ce qui m'a occupée pendant peut-être un mois de travail : avoir un lien permanent que vous fournissez, que vous utilisez, que vous diffusez - ça peut être un sous domaine (doc.eZplatform.com) tout simplement, ça peut être un répertoire mais attention ce lien il faut le maintenir (hello sysadmin !).

Quand vous faites des migrations d'outils, il faut gérer les redirections ça paraît un peu idiot mais je vous assure que des fois ça peut mal se passer.

N'hésitez pas donc à diffuser le lien.

Et au niveau valorisation dans l'entreprise si votre doc est une partie du produit, au même titre que les fonctionnalités, ça change vraiment la vision du produit : on va y apporter du soin et de la qualité.

D'ailleurs, faire un petit effort marketing dans le wording (toujours utiliser les mêmes mots dans vos plaquettes, dans vos sites de présentation... parce que parfois ça fait des choses bizarres.

On a des composants par exemple : est ce qu'on appelle ça un composant ? un plugin ? est ce que ça peut être un problème ? Interagissez avec votre communauté : s'ils galèrent tous à l'installer, votre doc d'installation est à revoir, améliorer si vous voyez qu'il ya une fonctionnalité qui est annoncée qui est très très attendue, peut-être qu'il va falloir mettre la gomme et apporter un soin particulier à la doc de cette fonctionnalité.

Sinon vous risquez d'avoir des utilisateurs mécontents et personne ne veut ça.

Vous pouvez aussi faire de l'analyse de traffic sur la doc : je pense à des choses comme google analytics. Par exemple, j'ai créé un tutoriel, j'ai regardé, et à l'étape 2 la majorité des lecteurs va à l'étape 3 et en plus ils viennent de l'étape 1, c'est plutôt cool.

Par contre je vois qu'il y en a plein qui retournent à l'étape 1 : 60% vont à l'étape 2 mais 40% retournent à l'étape 1, ça veut dire peut-être que mon étape 2 n'est pas claire, que ça s'est mal passé pour eux, qu'ils vérifient qu'eux n'ont pas raté quelque chose.

Donc ça ça peut aider.

Au niveau des outils, je n'ai listé que quelques outils (je voulais projeter mon navigateur web) il y a un comparateur de générateurs statique qui s'appelle staticgen.com (essaie de projeter le navigateur) Bon ok, vous ne verrez qu'une partie et j'en suis bien navrée Donc sur staticgen, voyez les plus populaires, l'idée c'est que vous pouvez choisir.

Il ya des petits fils par langage : est ce que vous voulez un générateur statique en PHP ? par langage de template : est ce que vous voulez utiliser jinja ou peut-être twig si vous êtes Symphonien par licence : est-ce que vous voulez utiliser un générateur statique sous licence MIT, GPL 2 ? Tous les goûts sont dans la nature ! Je suis en train de réfléchir très fort comment je vais projeter pour le reste Comme générateurs statiques les plus connus et populaires, je vais vous en citer, vous les trouvez tous sur staticgen (uniquement des générateurs open source) : Couscous, Hugo, Jekyll, Metalsmith, Gitbook, tous ceux là on les a testés, ils ne convenaient pas à notre besoin.

- on avait fait une liste et une grille de nos besoins - et celui qu'on a décidé d'utiliser, c'est un Read the docs (disponible en open source) on a décidé d'utiliser la version commerciale avec du support, pour que notre IT n'ait pas à gérer cette partie.

Je ne parle que de ce que je connais : l'idée c'est qu'il existe en deux parfums - markdown ou rST (rST derrière c'est Sphinx qui tourne, ce qui est utilisé pour la doc de Symfony).

Et un autre qui a le vent en poupe en ce moment c'est ASCII Doc (je retente la manœuvre) Donc ASCII Doc, c'est pas du markdown c'est du texte simple et il y a aussi un générateur statique (certains font leurs slides de conférence avec).

Je pense que je pourrais faire une conférence dédiée à ce sujet : pour les API vous utilisez peut-être Swagger Est-ce qu'il y en a qui connaissent Swagger ? Yes ! Il vous permet aussi de générer une documentation et je voulais vous citer un autre projet qui s'appelle Dredd qui va tester la description votre API Swagger au regard de l'API réelle pour que votre doc reste à jour (Dredd comme Judge Dredd) Au niveau de l'orthographe et de la grammaire, je travaille avec des documentations en anglais mais je vous ai cité des outils en français : il y a un dictionnaire des synonymes (le CRISCO) Vous voulez dire "le bidule est contenu dans le machin" mais vous en avez marre de vous exprimer toujours de la même manière, vous pouvez trouver des synonymes.

Pour l'orthographe y'a le projet Voltaire qui explique des règles orthographiques et qui propose même une certif En anglais moi j'utilise Grammarly qui checke la grammaire : typiquement si j'ai mis la virgule au mauvais endroit, les pluriels des verbes.

(J'avais prévu de vous montrer mais je verrai à la fin en fonction du temps qu'il me reste) Pour les expressions j'utilise Linguee, qui cherche, dans un corpus de sites publiés, les expressions par exemple comment on traduit en anglais "ils ont en commun tous les deux" ? Ou "le fond et la forme" : en français ça sonne bien, mais est-ce qu'il existe une expression anglaise dédiée ou est-ce qu'on traduit mot-à-mot "le fond et la forme" ? Pour le style il y a Hemingway App qui a été assez diffusée : est-ce qu'il y en a qui en ont déjà entendu parler ? Ok, alors ça faut que je vous le montre absolument Hemingway App : c'est pour le style et notamment le style adapté à l'écran ça vous fait des statistiques sur votre texte par exemple la phrase en rouge est trop longue merci de la découper en phrases plus courtes donc il existe en web, en appli desktop, (mais c'est que pour l'anglais malheureusement pour l'instant).

Hemingway écrivait avec un style très percutant, d'où le nom.

Pour la traduction collaborative, si jamais vous avez un projet où vous voulez que les gens traduisent votre doc ou votre projet (ça a été notre cas on voulait qu'ils traduisent l'interface) alors autant le traduire en français ça allait, j'ai aussi des Polonais dans mon entreprise des Allemands mais en japonais ou d'autres langues c'était un peu plus compliqué ! On a utilisé Crowdin (je mets mes screenshots : là c'est l'espace de travail de Crowdin).

Tout en haut il y a la chaîne en noir qui est "locate me".

A gauche c'est la liste des chaînes qu'on peut traduire. Et là il ya des suggestions : ici par Bing, et ici comme dans mon projet j'ai déjà utilisé cette traduction plusieurs fois peut-être que pour la cohérence ça serait bien de la réutiliser.

Et Crowdin a aussi un système où dans votre navigateur, en utilisant l'application, vous pouvez directement traduire dans l'interface.

Pour la traduction par des robots vous avez DeepL - je vous montre directement - j'ai copié une page sur les variables variables de PHP, et DeepL est un traducteur comme Google Translate, La version payante de DeepL vous donne accès à l'API.

L'intérêt c'est pré-traduire votre doc et de demander de la relecture à des locuteurs natifs.

Et puis tous vos outils de Webmastering (je parlais d'Opquast au début) sont toujours valables.

On me demande toujours s'il faut automatiser : oui, automatisez tout ce que vous pouvez.

Quand on a fait une migration depuis un Wiki Confluence à des fichiers markdown, on a automatisé le nom des fichiers, le changement du contenu ; c'était en one shot, on a un générateur statique, c'est automatisé. Mais il y a des choses comme le fait que la doc fasse partie du produit, le fait que la doc dans le processus de release des features : ça c'est plutôt humain, c'est plutôt un changement d'état d'esprit que vous ne pourrez pas automatiser.

Chez eZ systems on utilise du kanban donc avec plusieurs colonnes, et ça passe de doc... pardon je dis n'importe quoi ça passe de dev à doc puis à QA et la QA prend la fonctionnalité utilise la fonctionnalité en regardant la doc et s'il y a une erreur s'adresse à nous - doc et dev - en disant "ça ne marche pas comme prévu, qu'est-ce qu'il se passe ?" Est-ce qu'il y a une erreur dans la doc est ce que il y a un bug ? Donc là mon collègue, il a fait un POC de la "Doudou Lib" et il s'aperçoit qu'il n'a pas le temps de développer la fonctionnalité qui lui manque et de faire un travail de qualité sur la doc (je n'étais pas disponible pour l'aider à ce moment là sinon je l'aurais fait, je ne suis pas sans coeur) donc il a éliminé "Doudou Lib".

Du coup, contrairement à ce qu'on aurait pu croire au tout début il a choisi "Pote Lib" parce qu'il peut se faire aider, il va forcément monter en compétences dessus et la documentation existe, et il va pouvoir l'améliorer un petit peu.

Alors moi je vaquais à mes occupations tranquille, et tout à coup, il a surgi en disant "qu'est-ce que je peux faire tout de suite sur ma documentation ?" Et je m'y attendais pas du tout (tout comme personne ne s'attend à l'Inquisition espagnole).

Des repères pour tout de suite, des idées pour améliorer la doc existante - puisque que vous en avez tous une et ça me fait chaud au cœur, sachez-le ! Qu'est-ce qu'il faut arrêter de faire ? Des private jokes, surtout si votre doc vise un public mondial (il y a beaucoup de blagues sur Star wars, H2G2 - je sais même pas si tout le monde sait ce que signifie H2G2 le guide du routard galactique, même sur les Monty Python).

Ou alors vous fait des blagues et vous faites une page pour documenter vos blagues : donc là j'ai mis des liens et l'idée c'est que dans la doc de Python, il y a une page qui est sur des variables dans le texte et dans les fonctions, et dans cette page il y a à peu près toute les paroles (je résiste quand même pas, je suis désolée, je l'emporterai peut-être pas au paradis comme on dit) donc dans cete page, il y a toutes les paroles de ce superbe sketch ! C'est un consommateur qui se rend chez un marchand d'animaux pour un problème avec son perroquet : Le marchand demande quel est le problème et à la manière très anglaise des Monty Python, il lui dit eh bien ce perroquet est complètement mort L'autre dit "Absolument pas !" et tout le sketch est basé là-dessus.

Et donc ils ont des exemples dans leur doc.

(je ne sais pas si vous arrivez à lire je l'espère) mais à chaque fois qu'il y a des exemples sur les arguments il y a des exemples avec John Cleese, avec les Monty Python - puisque le langage Python quand-même a un rapport avec les Monty Python.

Tout ça pour dire les private jokes ça peut être un problème.

Au niveau du vocabulaire, stop à certains mots : si le niveau de langage est trop élevé, ça peut poser problème.

Si votre doc est en français, pour les gens qui sont pas natifs francophones ça peut être un problème.

Par exemple, si vous dites "nonobstant le paramètre, cette fonction doit retourner ceci ou cela" : si la personne est pas sûr à 100% du sens de nonobstant elle va devoir chercher elle va se sentir idiote donc c'est pas très agréable - et c'est pareil en anglais.

Attention au langage trop générique : "des données sont attendues en entrée". Quel type de données ? Soyez un peu plus précis.

Et, mon petit combat, dédicace aux personnes avec qui j'en ai parlé juste avant : utilisez des mots épicène c'est-à-dire n'utilisez pas épicène dans votre doc ! C'est un mot comme "ministre", on peut dire un ministre ou une ministre ça ne change pas ou dire une personne, ça ne présage pas du genre de la personne.

Dans vos exemple utiliser des prénoms un peu variés : si vous dites à chaque fois "le développeur", je me sens pas concerné parce que je suis pas un développeur ça peut paraître un détail pour vous mais ça peut être important pour certains.

Stop aux fautes d'orthographe ! C'est pas grave d'être mauvais en orthographe, mais faites-vous relire.

Je vous rappelle que tout peut arriver ! Donc ça c'est une private joke : Pascal Borreli, si tu regardes un jour cette vidéo...

Je me suis permise de la faire ici mais je ne le ferai pas dans la documentation.

Stop aux commentaires sur la page ! Les commentaires sur la page, j'ai envie de dire "c'est pas bien".

Exemple de la doc PHP : ça c'est la page sur le Type Hinting sur les classes et les objets et un commentaire qui date, de Marcus je ne sais plus qui, d'il y a neuf ans qui nous présente une petite fonction handleTypehint() (peut-être qu'elle est encore valable je ne suis pas qualifiée pour juger de cela) mais ça occupe de l'espace disponible et c'est dur de juger la qualité des commentaires sur une page de doc.

Préférez plutôt des forums ou des choses comme ça.

Commencez par contre les tests, commencez la QA sur votre doc.

Exemple : il s'agit d'une notice pour un escalier. "Quand vous montez serrez à droite, quand vous descendez serrez sur votre gauche afin que personne n'entre en collision".

Si vous mettez ça dans votre doc, vous voyez bien que ça n'a pas été testé, clairement ! Voilà des exemples pour tester vos docs : installez en suivant le manuel d'installation et pas votre version dans une VM je ne sais quoi, votre version dev super shiny...

Faites vos recherches sur Stack Overflow et autres : quels sont les problèmes que rencontrent les gens ? Regardez les redirections de doc ou le legacy (par exemple dans notre doc legacy, on avait mis un gif d'un bouquetin en train de taper sur un clavier et au bout de six mois, j'ai dit à mes collègues "vous avez remarqué on a changé la doc et que sur l'ancienne on a mis un gif de bouquetin ?" Ils m'ont dit "oui c'est vrai que c'est embêtant ce gif et puis la doc en plus elle est dure à lire maintenant" parce qu'au lieu de mettre noir sur blanc on l'avait mis en gris pour montrer qu'elle était deprecated - on avait fait ce choix mais ils ont mis un temps fou avant de se dire que ce n'était pas normal - mes propres collègues en interne - dédicace à eux !).

Voilà, testez la recherche dans votre doc aussi.

Commencez les peer reviews donc les revues : là on a l'exemple de quelqu'un qui se plaint (en plus c'est récent ça date du 8 mai 2018 sur Twitter) qui dit sur les graphes, les diagrammes, il a des gens qui utilisent AXES et AXIS et des fois qui prennent l'un pour l'autre, on n'y comprend plus rien.

Donc ça permet d'avoir de la cohérence.

Et commencez à ranger : ce sera presque ma conclusion. Si vous avez quatre catégories, Tuto, How-to, Guide et Référence et normalement chaque information va pouvoir harmonieusement se ranger dans l'une des catégories.

J'ai préparé des liens que je fournirai à l'AFUP, parce qu'il a fait un talk entier sur le sujet pour montrer pourquoi ces catégories, comment, pourquoi c'est important et je le remercie.

Et pour les plus gourmands d'entre vous, qui ont vraiment envie de passer au stade supérieur, de faire, comme moi, un métier de technical writer ou de faire ce rôle dans leur équipe, il y a la doc de la doc : il y a une communauté qui s'appelle write the docs qui a fait un guide sur comment écrire de la doc (en anglais).

Et il y a un projet qui s'appelle Feed Me, Read Me : c'est un repo Github, dans les issues, vous donnez le lien de votre README, de votre repo Github aussi ou ailleurs et ils vous le corrigent, ils vous font des review sur votre README, gracieusement, généreusement.

Pourquoi vous priver de cette qualité ? Il y a également Beautiful docs (comme un README) : une page avec plein de liens vers des docs de qualité.

J'ai tiré pas mal de mes exemples dedans.

Et - c'est un sujet hyper intéressant - il y a des gens qui ne s'occupent que de la documentation des API qui ont créé un événement : tout comme nous on a le PHP Tour, eux ils ont API the Docs.

Il n'y a que des confs sur la doc de l'API - moi je trouve ça fascinant, ça m'intéresse beaucoup, je ne sais pas si vous aurez le courage de regarder toutes les vidéos enregistrées, mais allez y jeter un oeil vous trouverez des outils, des explications d'outils assez chouettes.

Donc voilà où on en est. Et quand-même, la conclusion, c'est un peu le pitch que je vous ai fait au début : je me demande quand même pourquoi vous vous plaignez de la mauvaise qualité des docs...

et vous râlez quand vous devez en faire, c'est quand-même triste ! Voilà : no doc, no feature... c'est tout pour moi.

Il y a le temps pour des questions ? Donc j'ai pas lu ma dernière slide, ça résume ce que je vous ai dit.

Est ce que certains ont des questions auxquelles je pourrai répondre ? Romain d'Akeneo : justement on est éditeurs open source et on a une doc je voulais savoir comment vous mainteniez votre doc notamment les Cookbooks puisque d'une version à l'autre il y a toujours des changements techniques.

Est-ce que vous avez mis en place une intégration continue ? Est-ce que vous testez tout à la main ? Comment on fait évoluer les Cookbooks et leurs recipes (recettes) vu que ça change à chaque version ? Déjà ce que je n'ai pas précisé c'est qu'on a 15 développeurs et on est 3 à s'occuper de la doc, en plus des 15 développeurs, donc le ratio est plutôt bon, d'une part et d'autre part notre boulot en tant que team doc c'est de s'assurer qu'à chaque sprint - puisqu'on fonctionne avec un système de sprint - toutes les fonctionnalités livrées ont eu l'étape de doc Donc on met à jour à chaque sprint ce qui a été livré, les Cookbooks éventuellement, tout ce qui est à mettre à jour et la première fois qu on est intervenu sur les Cookbooks, on a fait un audit de la doc c'est à dire que fichier markdown par fichier markdown, on a reviewé et on est allés embêter les développeurs "Excuse moi est-ce que c'est encore valide ? Est-ce que je n'ai pas fait un contresens en changeant ta phrase ? Et que j'ai peut-être dit l'inverse de ce qui était vrai ?" Donc c'est du travail, on est 3 personnes à plein temps sur la doc mais du coup, à chaque sprint, on est en charge de vérifier que tous les livrables ont une doc.

Pour les régressions, c'est aussi une modification. En règle générale on fait aussi les release notes.

N'oublie pas ! Je me permets de te tutoyer, mais je ne fais pas ça avec tout le monde ! Donc on fait les release notes du coup quand y a une régression ça va être potentiellement indiqué et quand il ya une régression nous utilisons des petits outils comme des petites notes en vert, en jaune, des warnings, des outils pour attirer l'attention : "Attention, si vous utilisez la version 5.3.12, et qu'avant vous aviez la 5.3.11, il y a une modification : ce paramètre n'est plus optionnel".

Ce genre de choses. Je ne sais pas si tu pensais à ça.

Je sais pas s'il y a d'autres questions Bonjour et merci pour la présentation. Dans le cas où par exemple on utilise un logiciel pour lequel la doc serait assez mal maintenue dans le temps, qu'est-ce qu'on a pour mettre l'accent sur ce fait vis-à-vis de l'éditeur par exemple ? Savoir comment les pousser à mettre à jour leur documentation ? Je vais te vouvoyer si tu préfères Dans le cas où vous êtes utilisateur d'un logiciel dont la doc ne vous convient pas parce que pas mise à jour comment remonter l'info et dire "votre doc, là ça ne convient pas du tout, faites quelque chose" ? La première idée qui me vient à l'esprit c'est l'argent (j'espère que je ne vais pas être citée sur Twitter !) La première idée qui vient à l'esprit ça pourrait être une sorte de pression financière. Je vais répondre à l'inverse.

Par exemple : "la doc, ça serait bien qu'on la traduise en français, on a beaucoup d'utilisateurs en France".

Si je dis ça à mes product managers, je travaille chez un éditeur, ils vont me demander d'où je tiens cette info.

Je peux pas dire ça. Je vais dire qu'on a tant d'utilisateurs en France, tant de clients qui ont le support platinum, qui nous rapportent tant, je vais passer cinq jours de travail à traduire la doc en français du coup le retour sur investissement est intéressant, faisons le ! Voilà comment je vais argumenter.

C'est pour ça que je pensais à la partie financière.

Donc tout dépend de l'engagement et de la relation avec eux.

Menacer de les quitter et d'utiliser un autre outil c'est pas toujours possible, parfois tu es très dépendant.

Tu peux aussi écrire ta propre doc sur le sujet. Sérieusement, c'est-à-dire qu'à un moment, il y avait des wikis qui parlaient d'eZ publish, notre version legacy, et qu'on recommandait aux gens parce qu'ils était très bien faits mais c'était pas nous qui les avions édités à l'époque.

Donc tu peux décider de dire "moi je documente ça. Tant pis, ils le font pas, mais j'en ai besoin".

Tu peux la garder en interne ou la publier ça je ne sais pas.

Il y avait d'autres questions je ne sais pas si la personne est descendue.

C'est vrai que j'étais placé un peu loin déjà merci pour cette présentation.

Je voulais vous demander au niveau de la gestion de projet - vous avez en partie répondu à ma question avec la proportion développeurs / rédacteurs de doc vous pensez qu'il faudrait prévoir à peu près quel pourcentage de temps de rédaction de la doc, par rapport au temps de développement d'un projet par exemple ? Merci pour la question : ratio temps de dev / temps doc, ça rejoint un point que je n'ai pas abordé clairement : le public cible de votre produit, votre logiciel.

Si votre logiciel il est fait en interne, tout le monde sait de quoi il parle, l'API emploie des termes clairs que tout le monde emploie tous les jours, vous générez la doc d'API, vous êtes tranquille.

Si le projet est open source, que vous voulez que le monde entier l'utilise, il va falloir mettre plus d'efforts dans la doc. Donc je pourrais pas donner un ratio absolu.

Je peux aussi dire que les développeurs sont capables de faire du travail de documentation puisque j'étais développeuse avant Vous pouvez le faire.

Donc du coup les développeurs peuvent effectivement y consacrer du temps.

Il y a aussi - pour ceux qui utilisent des méthodes Agiles notamment Scrum - tout ce qui est Definition of Done : quand est-ce qu'on considère qu'une fonctionnalité est terminée ? Chez nous la fonctionnalité est terminée quand il y a le code, la doc et que la QA a validé que ça fonctionnait et que la doc ne racontait pas de sornettes, sur le sujet.

Notre Definition of Done, c'est celle là. Si la vôtre, c'est : la fonctionnalité fonctionne la couverture de test unitaire est au top par contre les tests fonctionnels ne sont pas dedans, la doc n'est pas dedans, vous aurez peut-être une doc de moins bonne qualité à moins que le monsieur qui a posé la question d'avant fasse la doc par lui-même parce qu'il en a marre de ne pas en avoir.

Donc j'ai du mal à répondre sur un chiffre précis, c'est plus une organisation d'équipe, et dire "ça fait partie du produit" c'est ça qui a changé les choses là où je travaille actuellement.

Quand je suis arrivée, il y avait de la doc et il y avait beaucoup de contenu, mais il n'était pas organisé.

En l'organisant, on s'est aperçu qu'il y avait des parties, comme les tests, qui n'étaient pas couvertes par la doc.

"Si tu connais, tu sais faire c'est bon et si tu connais pas, demande à ceux qui savent faire mais tu peux pas trouver par toi-même".

J'espère que j'ai répondu.

Merci.