Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Sans documentation, la fonctionnalité n'existe pas !

1.175 visualizaciones

Publicado el

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

Publicado en: Software
  • Sé el primero en comentar

  • Sé el primero en recomendar esto

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 !

×