Download to read offline
Uploaded bysarahhaim shl
No doc, no feature v2
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.
No doc, no feature v2
- 1. Sans documentation la fonctionnalité n’existepas. Sarah Haïm-Lubczanski Technical Writer – BIMData.io sarah@bimdata.io @sarahhaim
- 2.
- 3. BIM Optimizer @sarahhaim Photo bySeaman Apprentice Joshua Adam Nuzzo, U.S. Navy
- 4. BIM Optimizer @sarahhaim Doudou LibPote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
- 5. BIM Optimizer @sarahhaim Doudou LibPote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
- 6. BIM Optimizer Qualité dela doc.
- 7. BIM Optimizer @sarahhaim Qu’est-ce quifait partie de la doc ? Répondez sur : https://answergarden.ch/937300 $> whatis doc$> whatis doc
- 8. BIM Optimizer @sarahhaim ● README ● Releases Notes ● BestPractices ● 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 ● BestPractices ● 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 mesurerla qualité d’une doc ? Photo by epSos.de
- 11. BIM Optimizer @sarahhaim Critères dequalité 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 del’aide – Obtenir de l’aide directe – Contacter le support – Soumettre un bug https://docs.djangoproject.com/fr/2.0/
- 23. BIM Optimizer @sarahhaim Possibilité defeedbacks ● Feedback sur la doc et le produit ● Contributions
- 24. BIM Optimizer @sarahhaim Possibilité defeedbacks ● 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.
- 28.
- 29. BIM Optimizer @sarahhaim Doudou LibPote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++ Exit Shiny Lib
- 30. BIM Optimizer @sarahhaim Photo bySeaman 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 dela doc.
- 33. BIM Optimizer @sarahhaim Travailler sadocumentation ● Créer la documentation ● Maintenir la doc ● Valoriser la doc
- 34. BIM Optimizer @sarahhaim Maintenir ladoc ? ● 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 ladoc ? ● 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 etgrammaire ● 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 pardes robots ● DeepL : version payant = API
- 43. BIM Optimizer @sarahhaim Traduction pardes robots ● DeepL : version payant = API
- 44. BIM Optimizer @sarahhaim Webmaster ● Ettous 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 LibPote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
- 47.
- 48. BIM Optimizer @sarahhaim Des idéespour tout de suite.
- 49. BIM Optimizer @sarahhaim Stop itright 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 lesfautes d’orthographe ● Se relire ● Se faire relire
- 52. BIM Optimizer @sarahhaim Stop lescommentaires ● Commentaires utilisateurs sur la page
- 53. BIM Optimizer @sarahhaim Commencez lestests ● Testez votre doc ● exemples : – installation – Faites vos recherches sur Stack Overflow – Legacy et redirections – Testez votre recherche interne
- 54. BIM Optimizer @sarahhaim Commencez lestests ● Testez votre doc ● exemples : – installation – Faites vos recherches sur Stack Overflow – Legacy et redirections – Testez votre recherche interne
- 55. BIM Optimizer @sarahhaim Commencez lespeer 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 lesgourmands, 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 LibPote Lib Shiny Lib Savoir, expérience +++ + + Se faire aider ++ +++ ++ Documentation exhaustive + ++ +++
- 60. BIM Optimizer @sarahhaim Créer unedocumentation.
- 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 bySeaman Apprentice Joshua Adam Nuzzo, U.S. Navy
- 65. BIM Optimizer @sarahhaim #JPLQ ● Yaurait-il une corrélation entre – Qualité de la documentation des outils opensource – Enthousiasme des développeurs ?
- 66. BIM Optimizer @sarahhaim #JPLQ ● Yaurait-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 !