É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.

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 ?
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
100. Write the (good) doc Questions ? #bzhdoc
101. RTFM #bzhdoc