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.

Sans documentation, la fonctionnalité n'existe pas !

606 views

Published on

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

Published in: Software
  • Be the first to comment

  • Be the first to like this

Sans documentation, la fonctionnalité n'existe pas !

  1. 1. LA FONCTIONNALITÉ N’EXISTE PAS SANS DOCUMENTATION
  2. 2. NO FEATURE NO DOC
  3. 3. www.ez.nowww.ez.no @sarahhaim Bonjour Sarah Haïm-Lubczanski @sarahhaim @mereteresa ● Technical Writer ● Canard en plastique Photo by Tom Morris
  4. 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. 5. www.ez.nowww.ez.no @sarahhaim Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
  6. 6. www.ez.nowww.ez.no @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  7. 7. www.ez.nowww.ez.no @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  8. 8. DE LA DOC QUALITÉ
  9. 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. 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. 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. 12. www.ez.nowww.ez.no @sarahhaim Comment mesurer la qualité d’une doc ? Photo by epSos.de
  13. 13. www.ez.nowww.ez.no @sarahhaim Cohérence ● Texte, exemples, et images
  14. 14. www.ez.nowww.ez.no @sarahhaim Cohérence ● Texte, exemples, et images https://docs.docker.com/engine/docker-overview/#docker-architecture
  15. 15. www.ez.nowww.ez.no @sarahhaim Clarté ● Navigation ● Accessibilité ● Utilisabilité – Cf Opquast https://checklists.opquast.com/
  16. 16. www.ez.nowww.ez.no @sarahhaim Clarté ● Navigation ● Accessibilité ● Utilisabilité – Cf Opquast https://checklists.opquast.com/
  17. 17. www.ez.nowww.ez.no @sarahhaim Liens sémantiques ● Recommandation de contenu « ceci est en rapport »
  18. 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. 19. www.ez.nowww.ez.no @sarahhaim Fiabilité  ● Disponible ● Version consultée ● Date de mise à jour
  20. 20. www.ez.nowww.ez.no @sarahhaim Fiabilité  ● Disponible ● Version consultée ● Date de mise à jour
  21. 21. www.ez.nowww.ez.no @sarahhaim Qualité supérieure : langue natale ● Dans ma langue
  22. 22. www.ez.nowww.ez.no @sarahhaim Qualité supérieure : langue natale ● Dans ma langue
  23. 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. 24. www.ez.nowww.ez.no @sarahhaim Qualité de luxe ● « Google it » – Codes erreurs : avoir une référence
  25. 25. www.ez.nowww.ez.no @sarahhaim Qualité de luxe ● « Google it » – Codes erreurs : avoir une référence
  26. 26. www.ez.nowww.ez.no @sarahhaim Qualité de luxe : feedbacks ● Feedback sur la doc et le produit ● Contributions
  27. 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. 28. www.ez.nowww.ez.no @sarahhaim Qualité de luxe : Troubleshooting
  29. 29. www.ez.nowww.ez.no @sarahhaim Qualité de luxe : Troubleshooting https://developer.twitter.com/en/docs/basics/things-every-developer-should-know
  30. 30. www.ez.nowww.ez.no @sarahhaim Qualité de luxe : Troubleshooting
  31. 31. www.ez.nowww.ez.no @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  32. 32. www.ez.nowww.ez.no @sarahhaim Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
  33. 33. DE LA DOC QUOTIDIEN
  34. 34. www.ez.nowww.ez.no @sarahhaim Travailler sa documentation ● Créer la documentation ● Maintenir la doc ● Valoriser la doc
  35. 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. 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. 37. www.ez.nowww.ez.no @sarahhaim Créer la documentation ● Partez des spécifcations fonctionnelles ● Deux rubriques : – Installation – Utilisation
  38. 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. 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. 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. 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. 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. 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. 44. www.ez.nowww.ez.no @sarahhaim Traduction collaborative ● Crowdin
  45. 45. www.ez.nowww.ez.no @sarahhaim Traduction collaborative ● Crowdin
  46. 46. www.ez.nowww.ez.no @sarahhaim Traduction par des robots ● DeepL : version payant = API
  47. 47. www.ez.nowww.ez.no @sarahhaim Traduction par des robots ● DeepL : version payant = API
  48. 48. www.ez.nowww.ez.no @sarahhaim Webmaster ● Et tous vos outils de Webmaster – Logs – Performances – Etc.
  49. 49. www.ez.nowww.ez.no @sarahhaim Automatiser ? ● Oui mais... ● Processus de Release des fonctionnalités
  50. 50. www.ez.nowww.ez.no @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  51. 51. www.ez.nowww.ez.no @sarahhaim
  52. 52. POUR TOUT DE SUITE DES IDÉES
  53. 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. 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. 55. www.ez.nowww.ez.no @sarahhaim Stop les fautes d’orthographe ● Se relire ● Se faire relire
  56. 56. www.ez.nowww.ez.no @sarahhaim Stop les fautes d’orthographe ● Se relire ● Se faire relire Pascal Borreli is watching us
  57. 57. www.ez.nowww.ez.no @sarahhaim Stop les commentaires ● Commentaires utilisateurs sur la page
  58. 58. www.ez.nowww.ez.no @sarahhaim Stop les commentaires ● Commentaires utilisateurs sur la page
  59. 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. 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. 61. www.ez.nowww.ez.no @sarahhaim Commencez les peer reviews ● Faites des revues de la documentation
  62. 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. 63. www.ez.nowww.ez.no @sarahhaim Source : Daniele Procida / @EvilDMP
  64. 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. 65. www.ez.nowww.ez.no @sarahhaim Doudou Lib Pote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
  66. 66. www.ez.nowww.ez.no @sarahhaim Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
  67. 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 !

×