Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

No doc, no feature v2

60 views

Published on

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.

  • Be the first to comment

  • Be the first to like this

No doc, no feature v2

  1. 1. Sans documentation la fonctionnalité n’existe pas. Sarah Haïm-Lubczanski Technical Writer – BIMData.io sarah@bimdata.io @sarahhaim
  2. 2. No doc, no feature.
  3. 3. BIM Optimizer @sarahhaim Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
  4. 4. BIM Optimizer @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  5. 5. BIM Optimizer @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  6. 6. BIM Optimizer Qualité de la doc.
  7. 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. 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. 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. 10. BIM Optimizer @sarahhaim Comment mesurer la qualité d’une doc ? Photo by epSos.de
  11. 11. BIM Optimizer @sarahhaim Critères de qualité d’une doc ● Cohérence ● Clarté ● Liens sémantiques ● Fiabilité ● Langue ● Orientation ● Feedbacks ● Troubleshooting
  12. 12. BIM Optimizer @sarahhaim Cohérence ● Texte, exemples, et images
  13. 13. BIM Optimizer @sarahhaim Cohérence ● Texte, exemples, et images https://docs.docker.com/engine/docker-overview/#docker-architecture
  14. 14. BIM Optimizer @sarahhaim Clarté ● Navigation ● Accessibilité ● Utilisabilité – Cf Opquast https://checklists.opquast.com/
  15. 15. BIM Optimizer @sarahhaim Clarté ● Navigation ● Accessibilité ● Utilisabilité – Cf Opquast https://checklists.opquast.com/
  16. 16. BIM Optimizer @sarahhaim Liens sémantiques ● Recommandation de contenu « ceci est en rapport »
  17. 17. BIM Optimizer @sarahhaim Liens sémantiques ● Recommandation de contenu « ceci est en rapport » http://symfony.com/doc/current/controller.html
  18. 18. BIM Optimizer @sarahhaim Fiabilité ● Disponible ● Version consultée ● Date de mise à jour
  19. 19. BIM Optimizer @sarahhaim Fiabilité ● Disponible ● Version consultée ● Date de mise à jour
  20. 20. BIM Optimizer @sarahhaim Langue natale ● Dans ma langue
  21. 21. BIM Optimizer @sarahhaim Langue natale ● Dans ma langue
  22. 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. 23. BIM Optimizer @sarahhaim Possibilité de feedbacks ● Feedback sur la doc et le produit ● Contributions
  24. 24. BIM Optimizer @sarahhaim Possibilité de feedbacks ● Feedback sur la doc et le produit ● Contributions http://httpd.apache.org/docs-project/
  25. 25. BIM Optimizer @sarahhaim Error codes ● « Google it » – Codes erreurs : avoir une référence
  26. 26. BIM Optimizer @sarahhaim Error codes ● « Google it » – Codes erreurs : avoir une référence
  27. 27. BIM Optimizer @sarahhaim Troubleshooting
  28. 28. BIM Optimizer @sarahhaim Troubleshooting https://developer.twitter.com/en/docs/basics/things-every-developer-should-know
  29. 29. BIM Optimizer @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++ Exit Shiny Lib
  30. 30. BIM Optimizer @sarahhaim Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
  31. 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. 32. BIM Optimizer Quotidien de la doc.
  33. 33. BIM Optimizer @sarahhaim Travailler sa documentation ● Créer la documentation ● Maintenir la doc ● Valoriser la doc
  34. 34. BIM Optimizer @sarahhaim Maintenir la doc ? ● Mettre à jour le contenu ● Y compris supprimer ● Utiliser des outils en rapport avec votre besoin
  35. 35. BIM Optimizer @sarahhaim Rédacteur non-développeur ● Quel outillage ? – Wiki – Blogs tout faits – GED, base documentaire
  36. 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. 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. 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. 39. BIM Optimizer @sarahhaim Orthographe et grammaire ● Français – Synonymes: CRISCO – Orthographe : Projet Voltaire ● Anglais – Grammaire : Grammarly – Expressions : Linguee – Style : Hemingway App
  40. 40. BIM Optimizer @sarahhaim Traduction collaborative ● Crowdin – ex : https://crowdin.com/project/akeneo
  41. 41. BIM Optimizer @sarahhaim Traduction collaborative ● Crowdin – ex : https://crowdin.com/project/akeneo
  42. 42. BIM Optimizer @sarahhaim Traduction par des robots ● DeepL : version payant = API
  43. 43. BIM Optimizer @sarahhaim Traduction par des robots ● DeepL : version payant = API
  44. 44. BIM Optimizer @sarahhaim Webmaster ● Et tous vos outils de Webmaster – Logs – Performances – Etc.
  45. 45. BIM Optimizer @sarahhaim Automatiser ? ● Oui mais... ● Processus de Release des fonctionnalités
  46. 46. BIM Optimizer @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  47. 47. BIM Optimizer @sarahhaim
  48. 48. BIM Optimizer @sarahhaim Des idées pour tout de suite.
  49. 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. 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. 51. BIM Optimizer @sarahhaim Stop les fautes d’orthographe ● Se relire ● Se faire relire
  52. 52. BIM Optimizer @sarahhaim Stop les commentaires ● Commentaires utilisateurs sur la page
  53. 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. 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. 55. BIM Optimizer @sarahhaim Commencez les peer reviews ● Faites des revues de la documentation
  56. 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. 57. BIM Optimizer @sarahhaim ● Source : Daniele Procida / @EvilDMP ● https://www.divio.com/blog/documentation/
  58. 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. 59. BIM Optimizer @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  60. 60. BIM Optimizer @sarahhaim Créer une documentation.
  61. 61. BIM Optimizer @sarahhaim Que proposez-vous à vos utilisateurs ?Créer la documentation ● Partez des spécifications fonctionnelles ● Deux rubriques : – Installation – Utilisation
  62. 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. 63. BIM Optimizer @sarahhaim ● Apprendre ● Résoudre des problèmes – Installation – Utilisation de la feature principale – Utilisation des features expertes
  64. 64. BIM Optimizer @sarahhaim Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
  65. 65. BIM Optimizer @sarahhaim #JPLQ ● Y aurait-il une corrélation entre – Qualité de la documentation des outils opensource – Enthousiasme des développeurs ?
  66. 66. BIM Optimizer @sarahhaim #JPLQ ● Y aurait-il une corrélation entre – Qualité de la documentation des outils opensource – Enthousiasme des développeurs ?
  67. 67. BIM Optimizer @sarahhaim No doc, no feature ? ● Faites une QA pour la doc aussi ● Efforts à fournir existent dans votre taille ● Commencez immédiatement !

×