Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Écrire la (bonne) doc

Écrire la (bonne) doc

Présentée au BreizhCamp 2016 sous le titre "Write the (good) doc", cette conférence tente de présenter ce à quoi il faut faire attention lorsque l'on écrit de la doc, par où commencer, quelques conseils et bien sûr des exemples.

1e88e032d61a9343dca0a7fc9cccc7b4?s=128

Florian Strzelecki

March 25, 2016
Tweet

Transcript

  1. Write the (good) doc #bzhdoc Florian Strzelecki - @exirel Oscaro.com

  2. Qu'ont-ils en commun ? Suédois - 1943 Danois - 1932

  3. #bzhdoc Entre un système complexe d'assemblage de briques ?

  4. None
  5. #bzhdoc … et un meuble en kit ?

  6. #bzhdoc Suivez les instructions !

  7. • Simple • Étape par étape • Détaillé • Contextualisé

    • Accessible à tous • Reproductible
  8. • Simple • Étape par étape • Détaillé • Contextualisé

    • Accessible à tous • Reproductible • Linéaire • Limité à un seul résultat
  9. Et si… • Je veux faire un autre meuble ?

    • Ou construire un VAISSEAU SPATIAL ? #bzhdoc
  10. #bzhdoc SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP

    ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP ! SPACESHIP !
  11. #bzhdoc Lego nous raconte des histoires avec des instructions, et

    nous laisse inventer les nôtres.
  12. Lire la doc #bzhdoc

  13. Connaître ses lecteurs permet de savoir quoi leur dire. #bzhdoc

  14. Connaître ses lecteurs permet de savoir quoi leur écrire. #bzhdoc

  15. Des lecteurs de tous genres, de tous horizons, et de

    tous niveaux. #bzhdoc
  16. Il n'existe pas « une » doc pour tout le

    monde. Tout le monde a « sa » doc. #bzhdoc
  17. #bzhdoc Dites bonjour à vos lecteurs !

  18. Interlude Stéréotype vs Archétype

  19. Madame Rose « maman » B. • Aime ses chats,

    son jardin, et surtout ses enfants • Championne de Belote en ligne • Cultivée et grande lectrice #bzhdoc
  20. Un certain Florian S. • Encore au Lycée • Aime

    les jeux vidéos • #LesInternets • Voulait devenir écrivain quand il était plus jeune, mais développeur ça rapporte plus. #bzhdoc
  21. L'ouvrier Le jeune diplômé • Travaille en ESN • Débute

    en tout • Il a des amis imaginaires, comme stackoverflow #bzhdoc
  22. #bzhdoc La Bushi du Code • 15 kata matin et

    soir • KISS, DRY, YAGNI • Cherche l'équilibre parfait • Cache un sombre secret (PHP en ESN) • Compétences rares
  23. #bzhdoc Nils « R&D » G. • Projet top secret

    • Super edgy (early adopter) • Prototype en prod • 5 % d'optimisation du CA par ligne de code
  24. #bzhdoc Technicien système et réseau • home $ ssh CL3-FTTASK-V31

    • prod $ curl TOOLS_URL | sh • prod $ ./run_script-v2.sh • prod $ export DEBUG=1 • prod $ ./run_script-v2.sh \--force \--no-input
  25. #bzhdoc Technique Fonctionnel Professionnel Amateur

  26. #bzhdoc Chacun sa doc • Manuel utilisateur • Readme, Install,

    Release notes • How to & Tutoriel • Fonctionnalités & comportements • Références, spécifications, normes • Index, glossaire, dictionnaire, etc.
  27. Interlude Pourquoi la doc ? #bzhdoc Dédicace au temps perdu

  28. Écrire la doc #bzhdoc

  29. Les lecteurs doivent pouvoir s'approprier votre doc ! #bzhdoc

  30. Propriétés utiles (nécessaires?) • Raconter une histoire… non linéaire. •

    Rendre reproductible… et modulable. • Rester simple… tout en restant complet. • Être stable… et toujours à jour ! #bzhdoc
  31. Tout commence avec une histoire : celle du produit. #bzhdoc

  32. Interlude Placement produit

  33. Exemple : qui suis-je ? « Site e-commerce vendant des

    pièces automobiles compatibles avec des véhicules. » #bzhdoc
  34. #bzhdoc Au fait on recrute...

  35. L'histoire donne des repères, des clés de compréhension. #bzhdoc

  36. #bzhdoc Multiplier les points d'entrée.

  37. Points d'entrée • Quickstart : se lancer pour comprendre •

    Tutoriel : aller plus loin en partant des bases • Chapitres : plonger dans l'application • Installation : mettre en production • Références : chercher un détail • FAQ : trouver une réponse rapide • Code : lire la source, et peut-être contribuer ? #bzhdoc
  38. Des lecteurs différents prendront des chemins différents. Et c'est très

    bien. #bzhdoc
  39. Histoire : linéaire Points d'entrée : non-linéaire #bzhdoc

  40. #bzhdoc Adopter le bon niveau de granularité.

  41. Granularité • Vision d'ensemble • Fonctionnalités • Démarrage • Schéma

    d'architecture • Références fonction par fonction • Interfaces des composants • Exemple complet • Liste des dépendances #bzhdoc
  42. La granularité répond à des besoins précis – ceux des

    lecteurs. #bzhdoc
  43. Aller à l'essentiel #bzhdoc

  44. L'essentiel • Présenter d'abord le cas nominal • Ne pas

    se perdre en détails et digressions • Ce n'est pas un roman. #bzhdoc
  45. Commencer à écrire #bzhdoc

  46. Mettez tout sur une feuille. Faite ressortir l'essentiel. Écrivez 2

    à 5 lignes pour chaque point que vous aurez retenu. #bzhdoc
  47. Pour chaque partie essentielle : Recommencez. Et recommencez. Et recommencez

    encore. #bzhdoc
  48. N'ayez pas peur. Ce qui compte, c'est d'écrire. #bzhdoc

  49. Organiser le contenu #bzhdoc

  50. La lecture devrait être non-linéaire dans l'ensemble, mais elle reste

    toujours linéaire par bloc.
  51. Points d'entrée #bzhdoc

  52. Le premier niveau correspond aux types de documentation. Ce sont

    les points d'entrée.
  53. Granularité #bzhdoc

  54. Le second niveau est un découpage thématique au sein du

    premier niveau.
  55. Essentiel #bzhdoc

  56. Au delà il faut organiser des blocs cohérents en fonction

    de leur taille, et séparer les plus gros. #bzhdoc
  57. Uniformiser #bzhdoc

  58. Curseur de style Roman Factuel #bzhdoc Oui c'est vague.

  59. Des phrases courtes. Le sujet est actif. Un vocabulaire simple

    et précis. #bzhdoc
  60. Ref : Words To Avoid in Educational Writing • Simply,

    Clearly, Easy, etc. • However, So, Shall, Just, etc. • Source : https://css-tricks.com/words-avoid- educational-writing/ #bzhdoc
  61. Jargon & langue étrangère ne font pas toujours bon ménage

    pour certains lecteurs. #bzhdoc
  62. Limitez les digressions au strict minimum. Mettez en valeur les

    informations importantes. #bzhdoc
  63. L'attention du lecteur est limitée au problème qu'il veut résoudre.

    #bzhdoc
  64. Notes annexes • Évitez les hors-sujets, • Toutes les comparaisons

    ne se valent pas, • Préférez une forme neutre à une forme genrée (difficile en Français, facile en Anglais). • Les digressions tuent la compréhension. #bzhdoc
  65. Assurer la cohérence #bzhdoc

  66. Chaque partie doit être compréhensible avec le moins de pré-requis

    possible. #bzhdoc
  67. Partez du principe que le lecteur ne sait pas plus

    que le chapitre en cours. #bzhdoc
  68. Au lieu de se répéter, faites des liens entre deux

    parties distinctes mais liées. #bzhdoc
  69. Ouvrez vers l'extérieur : note & référence, norme & standard,

    documentation d'un autre projet. #bzhdoc
  70. Exemples • Norme & Standard de l'IETF • Définition des

    concepts métiers • Article wikipédia sur un algorithme, un concept • Lien vers la doc d'un autre projet • Lien vers le bug tracker, le dashboard, etc.
  71. Ne racontez pas l'Histoire. Pour ça, il y a Wikipédia.

    Et le Web en général. #bzhdoc
  72. Exemples #bzhdoc

  73. #bzhdoc

  74. #bzhdoc

  75. Type de doc (et du concret) #bzhdoc

  76. Bas niveau haut niveau → • Commentaire dans le code

    • Autodoc • Doc d'un projet technique (app/lib) • Interface & API • Manuel d'installation • Manuel Utilisateur #bzhdoc
  77. # Remoev last item if "url" in breadcrumb[-1]: breadcrumb[-1].pop("url", None)

    # Remove URL of the last item if "url" in breadcrumb[-1]: breadcrumb[-1].pop("url", None) # Breadcrumb last's item must not have # a link for SEO reasons. if "url" in breadcrumb[-1]: breadcrumb[-1].pop("url", None) Faute de frappe, commentaire erroné.. Anglais correct, mais impossible de répondre à la question : pourquoi ? Donne l'intention de l'auteur : si un quelqu'un d'autre lit ces lignes, il saura pourquoi elles existent. Commentaire dans le code #bzhdoc
  78. Expliquer pourquoi on fait quelque chose plutôt que dire qu'on

    fait quelque chose. #bzhdoc
  79. Autodoc #bzhdoc

  80. Comment ça marche • Générer à partir du code source

    • Basé sur les « docstrings » et les « annotations » • Implique une bonne couverture en commentaire • Très proche du code, notion « unitaire » #bzhdoc
  81. Générateur d'autodoc • JavaDoc (Java) • PHPDoc (PHP) • Doxygen

    (C, C++, et d'autres) • Sphinx (Python) (via extension + configuration) #bzhdoc
  82. Formater son code def order_total(basket, shipping=None): """Calculate order's total from

    a ``basket`` :param basket: Current basket :param shipping: Selected shipping method :return: Order's total price information :rtype: :class:`orders.OrderTotal` Order's total is calculated from: * The basket's total amount, * Minus the basket's total discount, * If given, the shipping cost (incl. VAT only). .. note:: The order's total excl. VAT does **not** include the shipping cost since it is only an incl. VAT price. The discount value is calculated from the price excl. tax, but its value is remove from the incl. tax only. """ # You don't need to read the code to understand what it does. #bzhdoc
  83. Autodoc • Granularité très fine (niveau unitaire) • Peu ou

    pas de vision d'ensemble • Référence du langage, de la bibliothèque, ou du code interne de l'application • Tendance à masquer les interactions entre les briques • Stabilité dépendante du code lui-même • Mais facile à mettre à jour #bzhdoc
  84. Ne jamais s'arrêter à autodoc. #bzhdoc

  85. La doc d'un projet technique (application/bibliothèque) #bzhdoc

  86. Découpage • Installation • Configuration • Topic • Topic avancé

    • Dev-Guide • Référence #bzhdoc
  87. Install & Config • Quickstart rapide • Ne donne que

    les instructions de bases • Donne une liste de dépendance • Ne détaille pas comment installer les dépendances • Propose une config minimale • Liste exhaustive des variables d'ENV/de conf • Indique ce qui est obligatoire et les valeurs par défaut #bzhdoc
  88. #bzhdoc Topic • Un chapitre par domaine de l'application •

    Exemple : – Navigation, – Catalogue, – Recherche – Panier, – Checkout, – Mon Compte.
  89. Topic : sous-niveau • Navigation : – Principes généraux (grille

    de navigation) – Construction des URLs – Fil d’Ariane – Voir aussi : SEO, Catalogue, Recherche #bzhdoc
  90. Topic : sous-niveau • Checkout : – Workflow global du

    checkout – Transporteurs – Adresses – Moyen de paiement – Placement de la commande – Intégration du PSP – Voir aussi : Commande, Remboursement, Retour #bzhdoc
  91. Topic avancé • Comme des topics, mais plus « transverse

    » • Parfois plus technique, lié à la vie du projet • Moins fonctionnel que technique • Exemples : – Traductions, – CRON, – Personnes à contacter, – Outils de tests, etc. #bzhdoc
  92. Dev-Guide • Lister les bonnes pratiques • Aider les nouveaux

    devs à entrer sur le projet • Documenter les outils autour du projet • Partager la même culture technique • Réduit le coût de formation #bzhdoc
  93. Référence • Autodoc ! • Liste des URLs pour les

    API #bzhdoc
  94. Bref. #bzhdoc

  95. Écrire #bzhdoc

  96. Écrivez souvent. Lisez plus. Persévérez. Recommencez. Corrigez. Améliorez. #bzhdoc

  97. Écrire pour être lu. #bzhdoc

  98. None
  99. None
  100. Write the (good) doc Questions ? #bzhdoc

  101. RTFM #bzhdoc