La nouvelle fonctionnalité est prête, tout le monde est ravi. Les utilisateurices vont-ils savoir s’en servir ? Si vous pensez que le changelog et la PHPDoc suffisent, je voudrais vous demander : pourquoi priver vos utilisateurices des meilleures parties de votre logiciel ? Je vous propose de définir la qualité minimale attendue pour une documentation et d’examiner l’effort à fournir pour l’atteindre. Nous parlerons des process de documentation et de comment on fait pour documenter avec les moyens et les compétences disponibles. Donnée au PHP Tour 2018 : https://event.afup.org/phptourmontpellier2018/programme/#2607

1. LA FONCTIONNALITÉ N’EXISTE PAS
SANS DOCUMENTATION

2. NO FEATURE
NO DOC

3. www.ez.nowww.ez.no
@sarahhaim
Bonjour
Sarah Haïm-Lubczanski
@sarahhaim
@mereteresa
● Technical Writer
● Canard en plastique
Photo by Tom Morris

4. www.ez.nowww.ez.no
@sarahhaim
Mon métier
● Savoir répondre à la question
● exemples :
– Nouveau paramètre d’une fonction
– Explications : How-to add Facebook
Connect?
Quelle est la place de cette information ?

5. www.ez.nowww.ez.no
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy

6. www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir,
expérience
+++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

7. www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir,
expérience
+++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

8. DE LA DOC
QUALITÉ

9. www.ez.nowww.ez.no
@sarahhaim
$> whatis doc$> whatis doc
Qu’est-ce qui fait partie de la doc ?
https://answergarden.ch/701736

10. www.ez.nowww.ez.no
@sarahhaim
●
README
●
Releases Notes
●
Best Practices
●
Code comments
doc générée→
$> whatis doc$> whatis doc
Qu’est-ce qui fait partie de la doc ?
https://answergarden.ch/701736

11. www.ez.nowww.ez.no
@sarahhaim
●
README
●
Releases Notes
●
Best Practices
●
Code comments
doc générée→
$> whatis doc$> whatis doc
Qu’est-ce qui fait partie de la doc ?
● Tutoriels
● Référence
● How-to, Cookbooks
● Guide, Concepts
https://answergarden.ch/701736

12. www.ez.nowww.ez.no
@sarahhaim
Comment mesurer la qualité d’une doc ?
Photo by epSos.de

13. www.ez.nowww.ez.no
@sarahhaim
Cohérence
● Texte, exemples, et images

14. www.ez.nowww.ez.no
@sarahhaim
Cohérence
● Texte, exemples, et images
https://docs.docker.com/engine/docker-overview/#docker-architecture

15. www.ez.nowww.ez.no
@sarahhaim
Clarté
● Navigation
● Accessibilité
● Utilisabilité
– Cf Opquast
https://checklists.opquast.com/

16. www.ez.nowww.ez.no
@sarahhaim
Clarté
● Navigation
● Accessibilité
● Utilisabilité
– Cf Opquast
https://checklists.opquast.com/

17. www.ez.nowww.ez.no
@sarahhaim
Liens sémantiques
● Recommandation de contenu
« ceci est en rapport »

18. www.ez.nowww.ez.no
@sarahhaim
Liens sémantiques
● Recommandation de contenu
« ceci est en rapport »
http://symfony.com/doc/current/controller.html

19. www.ez.nowww.ez.no
@sarahhaim
Fiabilité
● Disponible
● Version consultée
● Date de mise à jour

20. www.ez.nowww.ez.no
@sarahhaim
Fiabilité
● Disponible
● Version consultée
● Date de mise à jour

21. www.ez.nowww.ez.no
@sarahhaim
Qualité supérieure : langue natale
● Dans ma langue

22. www.ez.nowww.ez.no
@sarahhaim
Qualité supérieure : langue natale
● Dans ma langue

23. www.ez.nowww.ez.no
@sarahhaim
Qualité supérieure : offrir de l’aide
– Obtenir de l’aide
directe
– Contacter le
support
– Soumettre un bug
https://docs.djangoproject.com/fr/2.0/

24. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe
● « Google it »
– Codes erreurs : avoir une référence

25. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe
● « Google it »
– Codes erreurs : avoir une référence

26. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : feedbacks
● Feedback sur la doc et le produit
● Contributions

27. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : feedbacks
● Feedback sur la doc et le produit
● Contributions
http://httpd.apache.org/docs-project/

28. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : Troubleshooting

29. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : Troubleshooting
https://developer.twitter.com/en/docs/basics/things-every-developer-should-know

30. www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : Troubleshooting

31. www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

32. www.ez.nowww.ez.no
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy

33. DE LA DOC
QUOTIDIEN

34. www.ez.nowww.ez.no
@sarahhaim
Travailler sa documentation
● Créer la documentation
● Maintenir la doc
● Valoriser la doc

35. www.ez.nowww.ez.no
@sarahhaim
Que proposez-vous à vos utilisateurs ?
● Apprendre
● Résoudre des problèmes
– Installation
– Utilisation de la feature principale
– Utilisation des features expertes

36. www.ez.nowww.ez.no
@sarahhaim
Pourquoi écrire la doc ?
● Pour le futur
● Pour vos collaborateurs
– Collègues
– Clients
– Intégrateurs de votre produit
– Partenaires
– Contributeurs
● Pour obtenir des contributeurs
● Pour vous améliorer en écriture

37. www.ez.nowww.ez.no
@sarahhaim
Créer la documentation
● Partez des spécifcations fonctionnelles
● Deux rubriques :
– Installation
– Utilisation

38. www.ez.nowww.ez.no
@sarahhaim
Maintenir la doc ?
● Mettre à jour le contenu
● Y compris supprimer
● Utiliser des outils en rapport avec votre
besoin

39. www.ez.nowww.ez.no
@sarahhaim
Valoriser la doc ?
● Avoir un lien permanent à fournir
– doc.monproduit.com
– monproduit.com/docs
● Diffuser ce lien
– Et le maintenir, Hello, sysadmin !
● La doc est une partie du produit

40. www.ez.nowww.ez.no
@sarahhaim
Effort marketing
● Wording : utiliser les mêmes mots
● Interagir avec sa communauté
– Quels sont les diffcultés ?
– Qu’est-ce qui est attendu ?
● Analyses du trafc sur la doc
– Est-ce que les lecteurs vont à l’Etape 3 du
Tutoriel ?

41. www.ez.nowww.ez.no
@sarahhaim
Effort marketing
● Wording : utiliser les mêmes mots
● Interagir avec sa communauté
– Quels sont les diffcultés ?
– Qu’est-ce qui est attendu ?
● Analyses du trafc sur la doc
– Est-ce que les lecteurs vont à l’Etape 3 du
Tutoriel ?

42. www.ez.nowww.ez.no
@sarahhaim
Quelques outils
● Générateurs statiques
Comparateur : https://www.staticgen.com
● RtD : https://readthedocs.org
– MkDocs : markdown
– Sphinx : rST
● ASCII Doc
– https://asciidoctor.org/docs/asciidoc-writers-gu
ide/

43. www.ez.nowww.ez.no
@sarahhaim
Orthographe et grammaire
● Français
– Synonymes: CRISCO
– Orthographe : Projet Voltaire
● Anglais
– Grammaire : Grammarly
– Expressions : Linguee
– Style : Hemingway App

44. www.ez.nowww.ez.no
@sarahhaim
Traduction collaborative
● Crowdin

45. www.ez.nowww.ez.no
@sarahhaim
Traduction collaborative
● Crowdin

46. www.ez.nowww.ez.no
@sarahhaim
Traduction par des robots
● DeepL : version payant = API

47. www.ez.nowww.ez.no
@sarahhaim
Traduction par des robots
● DeepL : version payant = API

48. www.ez.nowww.ez.no
@sarahhaim
Webmaster
● Et tous vos outils de Webmaster
– Logs
– Performances
– Etc.

49. www.ez.nowww.ez.no
@sarahhaim
Automatiser ?
● Oui mais...
● Processus de Release des fonctionnalités

50. www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

51. www.ez.nowww.ez.no
@sarahhaim

52. POUR TOUT DE SUITE
DES IDÉES

53. www.ez.nowww.ez.no
@sarahhaim
Stop it right now !
● Private jokes
– Star Wars
– H2G2
– Même les Monty Python
● Ou alors...documentez-les !
https://docs.python.org/3.3/tutorial/controlflow.html#keyword-arguments
https://youtu.be/i5nSwRVR0sI

54. www.ez.nowww.ez.no
@sarahhaim
Stop à certains mots
● Niveau de langue trop recherché
● Langage trop générique
● Mots épicènes et inclusivité
– Bob et Alice

55. www.ez.nowww.ez.no
@sarahhaim
Stop les fautes d’orthographe
● Se relire
● Se faire relire

56. www.ez.nowww.ez.no
@sarahhaim
Stop les fautes d’orthographe
● Se relire
● Se faire relire
Pascal Borreli is
watching us

57. www.ez.nowww.ez.no
@sarahhaim
Stop les commentaires
● Commentaires utilisateurs sur la page

58. www.ez.nowww.ez.no
@sarahhaim
Stop les commentaires
● Commentaires utilisateurs sur la page

59. www.ez.nowww.ez.no
@sarahhaim
Commencez les tests
● Testez votre doc
● exemples :
– installation
– Faites vos recherches sur Stack Overfow
– Legacy et redirections
– Testez votre recherche interne

60. www.ez.nowww.ez.no
@sarahhaim
Commencez les tests
● Testez votre doc
● exemples :
– installation
– Faites vos recherches sur Stack Overfow
– Legacy et redirections
– Testez votre recherche interne

61. www.ez.nowww.ez.no
@sarahhaim
Commencez les peer reviews
● Faites des revues de la documentation

62. www.ez.nowww.ez.no
@sarahhaim
Commencez à ranger
● Vérifez si vous avez les 4 catégories
suivantes
Tutoriels Apprentissage
How-to Accomplissement d’une
tâche
Guide Explications
Référence Informations
Source : Daniele Procida / @EvilDMP

63. www.ez.nowww.ez.no
@sarahhaim
Source : Daniele Procida / @EvilDMP

64. www.ez.nowww.ez.no
@sarahhaim
Pour les gourmands, en avoir plus...
● La doc de la doc : Write The Docs
– http://www.writethedocs.org/guide/
● Feed Me, Read Me project :
– Faites vous aider pour votre README
– https://github.com/lappleapple/feedmereadmes
● Beautiful docs : liste des belles docs
– https://github.com/PharkMillups/beautiful-docs
● API the Docs : conf sur la doc d’API
– https://apithedocs.org

65. www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

66. www.ez.nowww.ez.no
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy

67. www.ez.nowww.ez.no
@sarahhaim
No doc, no feature ?
● Faites une QA pour la doc aussi
● Efforts à fournir existent dans votre taille
● Commencez immédiatement !