La nouvelle fonctionnalité est prête, toute l'entreprise se réjouit. Les utilisateur·ices vont-ils savoir s’en servir ? Si vous pensez que le changelog et la PHPDoc suffisent, je voudrais vous demander : pourquoi priver vos utilisateur·ices des meilleures parties de votre logiciel ? Je vous propose de définir la qualité minimale attendue pour une documentation aujourd'hui, 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 au sein de l'équipe.

1. Sans documentation
la fonctionnalité
n’existe pas.
Sarah Haïm-Lubczanski
Technical Writer – BIMData.io
sarah@bimdata.io
@sarahhaim

2. No doc,
no feature.

3. BIM Optimizer
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy

4. BIM Optimizer
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir,
expérience
+++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

5. BIM Optimizer
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir,
expérience
+++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

6. BIM Optimizer
Qualité de la doc.

7. BIM Optimizer
@sarahhaim
Qu’est-ce qui fait partie de la doc ?
Répondez sur :
https://answergarden.ch/937300
$> whatis doc$> whatis doc

8. BIM Optimizer
@sarahhaim
●
README
●
Releases Notes
●
Best Practices
●
Code comments
→ doc générée
Qu’est-ce qui fait partie de la doc ?
Répondez sur :
https://answergarden.ch/937300
$> whatis doc$> whatis doc

9. BIM Optimizer
@sarahhaim
●
README
●
Releases Notes
●
Best Practices
●
Code comments
→ doc générée
Qu’est-ce qui fait partie de la doc ?
● Tutoriels
● Référence
● How-to, Cookbooks
● Guide, Concepts
Répondez sur :
https://answergarden.ch/937300
$> whatis doc$> whatis doc

10. BIM Optimizer
@sarahhaim
Comment mesurer la qualité d’une doc ?
Photo by epSos.de

11. BIM Optimizer
@sarahhaim
Critères de qualité d’une doc
● Cohérence
● Clarté
● Liens sémantiques
● Fiabilité
● Langue
● Orientation
● Feedbacks
● Troubleshooting

12. BIM Optimizer
@sarahhaim
Cohérence
● Texte, exemples, et images

13. BIM Optimizer
@sarahhaim
Cohérence
● Texte, exemples, et images
https://docs.docker.com/engine/docker-overview/#docker-architecture

14. BIM Optimizer
@sarahhaim
Clarté
● Navigation
● Accessibilité
● Utilisabilité
– Cf Opquast
https://checklists.opquast.com/

15. BIM Optimizer
@sarahhaim
Clarté
● Navigation
● Accessibilité
● Utilisabilité
– Cf Opquast
https://checklists.opquast.com/

16. BIM Optimizer
@sarahhaim
Liens sémantiques
● Recommandation de contenu
« ceci est en rapport »

17. BIM Optimizer
@sarahhaim
Liens sémantiques
● Recommandation de contenu
« ceci est en rapport »
http://symfony.com/doc/current/controller.html

18. BIM Optimizer
@sarahhaim
Fiabilité
● Disponible
● Version consultée
● Date de mise à jour

19. BIM Optimizer
@sarahhaim
Fiabilité
● Disponible
● Version consultée
● Date de mise à jour

20. BIM Optimizer
@sarahhaim
Langue natale
● Dans ma langue

21. BIM Optimizer
@sarahhaim
Langue natale
● Dans ma langue

22. BIM Optimizer
@sarahhaim
Ofrir de l’aide
– Obtenir de l’aide directe
– Contacter le support
– Soumettre un bug
https://docs.djangoproject.com/fr/2.0/

23. BIM Optimizer
@sarahhaim
Possibilité de feedbacks
● Feedback sur la doc et le produit
● Contributions

24. BIM Optimizer
@sarahhaim
Possibilité de feedbacks
● Feedback sur la doc et le produit
● Contributions
http://httpd.apache.org/docs-project/

25. BIM Optimizer
@sarahhaim
Error codes
● « Google it »
– Codes erreurs : avoir une référence

26. BIM Optimizer
@sarahhaim
Error codes
● « Google it »
– Codes erreurs : avoir une référence

27. BIM Optimizer
@sarahhaim
Troubleshooting

28. BIM Optimizer
@sarahhaim
Troubleshooting
https://developer.twitter.com/en/docs/basics/things-every-developer-should-know

29. BIM Optimizer
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++
Exit Shiny Lib

30. BIM Optimizer
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy

31. BIM Optimizer
@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 ?

32. BIM Optimizer
Quotidien de la doc.

33. BIM Optimizer
@sarahhaim
Travailler sa documentation
● Créer la documentation
● Maintenir la doc
● Valoriser la doc

34. BIM Optimizer
@sarahhaim
Maintenir la doc ?
● Mettre à jour le contenu
● Y compris supprimer
● Utiliser des outils en rapport avec votre besoin

35. BIM Optimizer
@sarahhaim
Rédacteur non-développeur
● Quel outillage ?
– Wiki
– Blogs tout faits
– GED, base documentaire

36. BIM Optimizer
@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

37. BIM Optimizer
@sarahhaim
Effort marketing
● Wording : utiliser les mêmes mots
● Interagir avec sa communauté
– Quels sont les difficultés ?
– Qu’est-ce qui est attendu ?
● Analyses du trafic sur la doc
– Est-ce que les lecteurs vont à l’Etape 3 du Tutoriel ?

38. BIM Optimizer
@sarahhaim
Effort marketing
● Wording : utiliser les mêmes mots
● Interagir avec sa communauté
– Quels sont les difficultés ?
– Qu’est-ce qui est attendu ?
● Analyses du trafic sur la doc
– Est-ce que les lecteurs vont à l’Etape 3 du Tutoriel ?

39. BIM Optimizer
@sarahhaim
Orthographe et grammaire
● Français
– Synonymes: CRISCO
– Orthographe : Projet Voltaire
● Anglais
– Grammaire : Grammarly
– Expressions : Linguee
– Style : Hemingway App

40. BIM Optimizer
@sarahhaim
Traduction collaborative
● Crowdin
– ex : https://crowdin.com/project/akeneo

41. BIM Optimizer
@sarahhaim
Traduction collaborative
● Crowdin
– ex : https://crowdin.com/project/akeneo

42. BIM Optimizer
@sarahhaim
Traduction par des robots
● DeepL : version payant = API

43. BIM Optimizer
@sarahhaim
Traduction par des robots
● DeepL : version payant = API

44. BIM Optimizer
@sarahhaim
Webmaster
● Et tous vos outils de Webmaster
– Logs
– Performances
– Etc.

45. BIM Optimizer
@sarahhaim
Automatiser ?
● Oui mais...
● Processus de Release des fonctionnalités

46. BIM Optimizer
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

47. BIM Optimizer
@sarahhaim

48. BIM Optimizer
@sarahhaim
Des idées pour tout de suite.

49. BIM Optimizer
@sarahhaim
Stop it right now !
● Private jokes
– Star Wars
– H2G2
– Même les Monty Python
● Ou alors...documentez-les !
– Doc Python :
https://docs.python.org/3.3/tutorial/controlflow.html
#keyword-arguments
– Sketch Dead Parrot (Monty Python)
https://youtu.be/vZw35VUBdzo

50. BIM Optimizer
@sarahhaim
Stop à certains mots
● Niveau de langue trop recherché
● Langage trop générique
● Mots épicènes et inclusivité
– Bob et Alice

51. BIM Optimizer
@sarahhaim
Stop les fautes d’orthographe
● Se relire
● Se faire relire

52. BIM Optimizer
@sarahhaim
Stop les commentaires
● Commentaires utilisateurs sur la page

53. BIM Optimizer
@sarahhaim
Commencez les tests
● Testez votre doc
● exemples :
– installation
– Faites vos recherches sur Stack Overflow
– Legacy et redirections
– Testez votre recherche interne

54. BIM Optimizer
@sarahhaim
Commencez les tests
● Testez votre doc
● exemples :
– installation
– Faites vos recherches sur Stack Overflow
– Legacy et redirections
– Testez votre recherche interne

55. BIM Optimizer
@sarahhaim
Commencez les peer reviews
● Faites des revues de la documentation

56. BIM Optimizer
@sarahhaim
Commencez à ranger
● Vérifiez 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

57. BIM Optimizer
@sarahhaim
●
Source : Daniele Procida / @EvilDMP
●
https://www.divio.com/blog/documentation/

58. BIM Optimizer
@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

59. BIM Optimizer
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++

60. BIM Optimizer
@sarahhaim
Créer une documentation.

61. BIM Optimizer
@sarahhaim
Que proposez-vous à vos utilisateurs ?Créer la
documentation
● Partez des spécifications fonctionnelles
● Deux rubriques :
– Installation
– Utilisation

62. BIM Optimizer
@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-guide/

63. BIM Optimizer
@sarahhaim
● Apprendre
● Résoudre des problèmes
– Installation
– Utilisation de la feature principale
– Utilisation des features expertes

64. BIM Optimizer
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy

65. BIM Optimizer
@sarahhaim
#JPLQ
● Y aurait-il une corrélation entre
– Qualité de la documentation des outils opensource
– Enthousiasme des développeurs ?

66. BIM Optimizer
@sarahhaim
#JPLQ
● Y aurait-il une corrélation entre
– Qualité de la documentation des outils opensource
– Enthousiasme des développeurs ?

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