Successfully reported this slideshow.
Your SlideShare is downloading. ×

Sauve un-e dev, écris une doc

Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Loading in …3
×

Check these out next

1 of 56 Ad

More Related Content

Recently uploaded (20)

Advertisement

Sauve un-e dev, écris une doc

  1. 1. Architecturer Ecrire Améliorer twitter : @sarahhaim Sauve un dev, écris une doc
  2. 2. twitter : @sarahhaim Programme ● Architecturer ● Ecrire ● Améliorer Crédits : @ThePracticalDev
  3. 3. twitter : @sarahhaim Mythe du code auto-documenté ● Pas de commentaires ● Pas de doc Crédits : Udiprai0329, CC BY-SA 4.0
  4. 4. twitter : @sarahhaim Parlons des dévs !
  5. 5. twitter : @sarahhaim Réalité ● Users ne savent pas que le logiciel existe ● Ni à quel problème il répond
  6. 6. twitter : @sarahhaim Installation ● Un Getting Started ● Le fichier INSTALL.md ● Liste des Pré-requis Hughes Aircraft Company, Public domain
  7. 7. twitter : @sarahhaim Et quand il y a des bugs ? ● Abandon ● Plaintes sur Twitter
  8. 8. twitter : @sarahhaim Quand le dév devient un user
  9. 9. twitter : @sarahhaim Sarah Haïm-Lubczanski ● Dev PHP > Technical Writer > Documentation Architect – J’aime les Monty Python, faire du vélo, manger de la pizza, et apprendre des nouvelles choses ● Twitter : @mereteresa / @sarahhaim Crédit : Tom Anguiano/MidJourney
  10. 10. Architecturer Ecrire Améliorer twitter : @sarahhaim Architecturer
  11. 11. Architecturer twitter : @sarahhaim Le contexte ● Situation ● Besoin métier Crédits : Sapeurs-Pompiers Du Bas-Rhin / Via Reuters
  12. 12. Architecturer twitter : @sarahhaim Dans la doc ? ● README, ● Tutoriels, ● Release notes Crédits : nathan williams from London, UK, CC BY 2.0
  13. 13. Architecturer twitter : @sarahhaim Orienter l’utilisateur Crédit : Rahubaddhah, CC BY-SA 4.0
  14. 14. Architecturer twitter : @sarahhaim En architecturant la doc ● Par type de contenu – framework Diataxis ● Par contexte, feature, étapes du processus
  15. 15. Architecturer twitter : @sarahhaim Framework Diataxis
  16. 16. Architecturer twitter : @sarahhaim Exemple d’utilisation de diataxis
  17. 17. Architecturer twitter : @sarahhaim
  18. 18. Architecturer twitter : @sarahhaim Notion d'audience ● Rejoint le persona en UX ● Rôle de l’utilisateur-ice
  19. 19. Architecturer twitter : @sarahhaim Point diversité de l’audience ● C’est documenté ! ● Stick & Stones… Microaggressions & Inclusive Language at Work – par Cory Williamson-Cardneau – [+ d’informations] Crédit : Benetton Group
  20. 20. Architecturer twitter : @sarahhaim Connaître son audience ? ● se rapprocher – du Marketing – du Support, – du Dev relations
  21. 21. Architecturer twitter : @sarahhaim Le bon chasseur ● La différence entre une bonne doc et une mauvaise doc ? – L’UX – La DX même !
  22. 22. Architecturer twitter : @sarahhaim audience x contexte
  23. 23. Architecturer twitter : @sarahhaim Pas une fin en soi ● Doc = outil ● On peut tout faire à la main Crédits : Jiří Sedláček, CC BY-SA 4.0
  24. 24. Architecturer Ecrire Améliorer twitter : @sarahhaim Ecrire
  25. 25. Ecrire twitter : @sarahhaim Une petite équipe ?
  26. 26. Ecrire twitter : @sarahhaim Kelsey Hightower Publish the solution 4 Search for an existing solution 2 Prove to ourselves the solution works 3 Attempt to understand the problem 1 Developer Loop https://github.com/ kelseyhightower/ kubernetes-the-hard-way
  27. 27. Ecrire twitter : @sarahhaim Write the content solving the issue 4 Create a plan for solving it 2 Use commons designs patterns 3 Understand the problem of your users 1 Writer Loop
  28. 28. Ecrire twitter : @sarahhaim Write the content so lving the issue 4 Create a plan for solving it 2 Use commons designs patterns 3 Understand the problem of your users 1 Writer Loop Publish the solution 4 Search for an existing solution 2 Prove to ourselves the solution works 3 Attempt to understand the problem 1 Developer Loop
  29. 29. Ecrire twitter : @sarahhaim Langages et formats
  30. 30. Ecrire twitter : @sarahhaim Ecrire une page de doc ● Audience ● Type de doc ● But de la « page » = Titre
  31. 31. Ecrire twitter : @sarahhaim Peur de la page blanche ? ● Utiliser un résumé ● Ecrire les phrases clefs ● Etoffer
  32. 32. Ecrire twitter : @sarahhaim Toujours bloqué ? ● Changer de média ● Parler à votre canard en plastique ● Utiliser des templates Crédit : National Institute of Standards and Technology Mathematician & computer expert Ida Rhodes worked at NBS from 1940-1975.
  33. 33. Ecrire twitter : @sarahhaim Des images dans la doc ● Icônes ● Schémas ● Copies d’écrans
  34. 34. Ecrire twitter : @sarahhaim Les schémas dans la doc
  35. 35. Ecrire twitter : @sarahhaim Copies d’écrans ● SUI : Simplified User Interface ● Masquer des éléments – Lisibilité
  36. 36. Ecrire twitter : @sarahhaim Docs « moches » / bonne UX ● Man pages Linux
  37. 37. Ecrire twitter : @sarahhaim Mettre en valeur le contenu ● Callout : Notes, warnings ● Mettre en gras ● Utiliser des listes à puces ● Trop long ? Divisez !
  38. 38. Ecrire twitter : @sarahhaim Inclure du code dans la doc ● Exécutable ● Explicatif ● Mettre différents niveaux de complexité si possible
  39. 39. Ecrire twitter : @sarahhaim Maintenir les exemples à jour ! ● Code copié-collé
  40. 40. Ecrire twitter : @sarahhaim Outillage ● La doc de la doc : Write The Docs – http://www.writethedocs.org/guide/ ● Faites vous aider pour votre README – ReadMe Checklist (ddbeck) – Feedmereadmes (lappleApple)
  41. 41. Ecrire twitter : @sarahhaim Dictionnaires ● Français – Synonymes : CRISCO ● Anglais – Expressions : Linguee – Collins Dictionnary – Word Reference
  42. 42. Ecrire twitter : @sarahhaim Correcteur orthographique ● Language Tool
  43. 43. Ecrire twitter : @sarahhaim Cohérence
  44. 44. Ecrire twitter : @sarahhaim Styleguide de la doc ● Google Developers Styleguide
  45. 45. Architecturer Ecrire Améliorer twitter : @sarahhaim Améliorer
  46. 46. Améliorer twitter : @sarahhaim Attendus de la doc ● Doc est un outil ! ● Gain de temps ● Apprentissage
  47. 47. Améliorer twitter : @sarahhaim Versionning ● Quelle version est affichée ● Changer de version Docusaurus.io
  48. 48. Améliorer twitter : @sarahhaim Doc du produit Legacy ● Quel impact sur la vie du projet pour le user ? ● Et pour l'UX ?
  49. 49. Améliorer twitter : @sarahhaim Documentation à jour ● Date de mise à jour ● Doc fraîche ! – Pas de doc périmée Crédits : Editions Albert René
  50. 50. Améliorer twitter : @sarahhaim Rechercher dans la doc ● Architecturer ● SEO ● Moteur de recherche – https://www.meilisearch.com
  51. 51. Améliorer twitter : @sarahhaim Faire une bonne doc ? ● Copier vos doc préférées ● Suivre un guide
  52. 52. twitter : @sarahhaim La doc est un outil de communication
  53. 53. twitter : @sarahhaim En quoi une doc va sauver le dev ? ● Gain de temps ● Aide réelle ● Communication des choix ● Learning : best practices
  54. 54. twitter : @sarahhaim Crédit :ironypoisoning, CC BY-SA 2.0 Merci https://joind.in/talk/aafe8
  55. 55. twitter : @sarahhaim Références / outils ● Styleguides / aide écriture – MS https://learn.microsoft.com/en-us/style-guide/ welcome/ – Google Developer https://developers.google.com/style – Chicago MS online https://www.chicagomanualofstyle.org/book/e d17/frontmatter/toc.html – Gitlab https://docs.gitlab.com/ee/development/docu mentation/styleguide/#location-and-naming-of -documents – A list apart blog https://alistapart.com/about/style-guide/ – Tone and voice https://brandland.zendesk.com/copywriting#to ne-and-voice ● La doc de la doc – https://www.writethedocs.org/guide/ ● Framework de rangement – Diataxis ● https://diataxis.fr/ – How to make sense of any mess https://www.howtomakesenseofanymess.com/ ● Gitlab documentation workflow https://about.gitlab.com/handbook/product/ux/technica l-writing/workflow/ ● Cours de Tech Writing Google – https://developers.google.com/tech-writing
  56. 56. twitter : @sarahhaim Références / templates Readme checklist – https://github.com/ddbeck/readme-checklist/blob/ main/checklist.md – https://github.com/hackergrrl/art-of-readme#bonus -the-readme-checklist ● Readme template de zalando – https://github.com/zalando/zalando-howto-open-s ource/blob/master/READMEtemplate.md ● Standard Readme – https://github.com/RichardLitt/standard-readme/ ● Concept template – https://docs.google.com/document/d/17PJ6kOazLi LSl0465sZcUbujh_g9_g6WKOv1IcxQDPs/edit?us p=sharing ● The Good Docs Project – https://thegooddocsproject.dev Dictionnaires ● FR / Synonymes http://crisco.unicaen.fr/dictionnaire-electronique-des-synony mes/actualites-des/ ● Traduction – EN / FR / ortho et grammaire LanguageTool https://languagetool.org/fr – DeepL https://www.deepl.com/translator – Linguee https://www.linguee.fr/ ● AlexJS : alex helps you find gender favouring, polarising, race related, religion inconsiderate, or other unequal phrasing – https://alexjs.com et package Vale https://vale.sh/hub/alex/ ● Convertir du contenu avec Pandoc – https://pandoc.org/getting-started.html

×