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.

Florian Strzelecki

March 25, 2016
Tweet

More Decks by Florian Strzelecki

Other Decks in Technology

Transcript

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  4. #bzhdoc
    … et un meuble en kit ?

    View full-size slide

  5. #bzhdoc
    Suivez les instructions !

    View full-size slide


  6. Simple

    Étape par étape

    Détaillé

    Contextualisé

    Accessible à tous

    Reproductible

    View full-size slide


  7. Simple

    Étape par étape

    Détaillé

    Contextualisé

    Accessible à tous

    Reproductible

    Linéaire

    Limité à un seul
    résultat

    View full-size slide

  8. Et si…

    Je veux faire un autre meuble ?

    Ou construire un VAISSEAU SPATIAL ?
    #bzhdoc

    View full-size slide

  9. #bzhdoc
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !
    SPACESHIP ! SPACESHIP !

    View full-size slide

  10. #bzhdoc
    Lego nous raconte des
    histoires avec des
    instructions, et nous laisse
    inventer les nôtres.

    View full-size slide

  11. Lire la doc
    #bzhdoc

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  14. Des lecteurs de tous genres,
    de tous horizons, et de tous
    niveaux.
    #bzhdoc

    View full-size slide

  15. Il n'existe pas « une » doc
    pour tout le monde.
    Tout le monde a « sa » doc.
    #bzhdoc

    View full-size slide

  16. #bzhdoc
    Dites bonjour à vos lecteurs !

    View full-size slide

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

    View full-size slide

  18. Madame Rose « maman » B.

    Aime ses chats, son
    jardin, et surtout ses
    enfants

    Championne de
    Belote en ligne

    Cultivée et grande
    lectrice
    #bzhdoc

    View full-size slide

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

    View full-size slide

  20. L'ouvrier Le jeune diplômé

    Travaille en ESN

    Débute en tout

    Il a des amis
    imaginaires, comme
    stackoverflow
    #bzhdoc

    View full-size slide

  21. #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

    View full-size slide

  22. #bzhdoc
    Nils « R&D » G.

    Projet top secret

    Super edgy (early
    adopter)

    Prototype en prod

    5 % d'optimisation du
    CA par ligne de code

    View full-size slide

  23. #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

    View full-size slide

  24. #bzhdoc
    Technique
    Fonctionnel
    Professionnel
    Amateur

    View full-size slide

  25. #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.

    View full-size slide

  26. Interlude
    Pourquoi la doc ?
    #bzhdoc Dédicace au temps perdu

    View full-size slide

  27. Écrire la doc
    #bzhdoc

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  30. Tout commence avec une
    histoire : celle du produit.
    #bzhdoc

    View full-size slide

  31. Interlude
    Placement produit

    View full-size slide

  32. Exemple : qui suis-je ?
    « Site e-commerce vendant
    des pièces automobiles
    compatibles avec des
    véhicules. »
    #bzhdoc

    View full-size slide

  33. #bzhdoc Au fait on recrute...

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  37. Des lecteurs différents
    prendront des chemins
    différents. Et c'est très bien.
    #bzhdoc

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  41. La granularité répond à des
    besoins précis – ceux des
    lecteurs.
    #bzhdoc

    View full-size slide

  42. Aller à l'essentiel
    #bzhdoc

    View full-size slide

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

    View full-size slide

  44. Commencer à écrire
    #bzhdoc

    View full-size slide

  45. Mettez tout sur une feuille.
    Faite ressortir l'essentiel.
    Écrivez 2 à 5 lignes pour chaque
    point que vous aurez retenu.
    #bzhdoc

    View full-size slide

  46. Pour chaque partie essentielle :
    Recommencez.
    Et recommencez.
    Et recommencez encore.
    #bzhdoc

    View full-size slide

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

    View full-size slide

  48. Organiser le contenu
    #bzhdoc

    View full-size slide

  49. La lecture devrait être non-linéaire
    dans l'ensemble, mais elle reste
    toujours linéaire par bloc.

    View full-size slide

  50. Points d'entrée
    #bzhdoc

    View full-size slide

  51. Le premier niveau correspond aux
    types de documentation.
    Ce sont les points d'entrée.

    View full-size slide

  52. Granularité
    #bzhdoc

    View full-size slide

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

    View full-size slide

  54. Essentiel
    #bzhdoc

    View full-size slide

  55. Au delà il faut organiser des blocs
    cohérents en fonction de leur taille,
    et séparer les plus gros.
    #bzhdoc

    View full-size slide

  56. Uniformiser
    #bzhdoc

    View full-size slide

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

    View full-size slide

  58. Des phrases courtes.
    Le sujet est actif.
    Un vocabulaire simple et précis.
    #bzhdoc

    View full-size slide

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

    View full-size slide

  60. Jargon & langue étrangère ne
    font pas toujours bon
    ménage pour certains
    lecteurs.
    #bzhdoc

    View full-size slide

  61. Limitez les digressions au strict
    minimum. Mettez en valeur les
    informations importantes.
    #bzhdoc

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  64. Assurer la cohérence
    #bzhdoc

    View full-size slide

  65. Chaque partie doit être
    compréhensible avec le moins de
    pré-requis possible.
    #bzhdoc

    View full-size slide

  66. Partez du principe que le
    lecteur ne sait pas plus que le
    chapitre en cours.
    #bzhdoc

    View full-size slide

  67. Au lieu de se répéter, faites des liens
    entre deux parties distinctes mais
    liées.
    #bzhdoc

    View full-size slide

  68. Ouvrez vers l'extérieur : note &
    référence, norme & standard,
    documentation d'un autre projet.
    #bzhdoc

    View full-size slide

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

    View full-size slide

  70. Ne racontez pas l'Histoire.
    Pour ça, il y a Wikipédia.
    Et le Web en général.
    #bzhdoc

    View full-size slide

  71. Exemples
    #bzhdoc

    View full-size slide

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

    View full-size slide

  73. Bas niveau haut niveau


    Commentaire dans le code

    Autodoc

    Doc d'un projet technique (app/lib)

    Interface & API

    Manuel d'installation

    Manuel Utilisateur
    #bzhdoc

    View full-size slide

  74. # 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

    View full-size slide

  75. Expliquer pourquoi on fait
    quelque chose plutôt que dire
    qu'on fait quelque chose.
    #bzhdoc

    View full-size slide

  76. Autodoc
    #bzhdoc

    View full-size slide

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

    View full-size slide

  78. Générateur d'autodoc

    JavaDoc (Java)

    PHPDoc (PHP)

    Doxygen (C, C++, et d'autres)

    Sphinx (Python) (via extension + configuration)
    #bzhdoc

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  81. Ne jamais s'arrêter à
    autodoc.
    #bzhdoc

    View full-size slide

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

    View full-size slide

  83. Découpage

    Installation

    Configuration

    Topic

    Topic avancé

    Dev-Guide

    Référence
    #bzhdoc

    View full-size slide

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

    View full-size slide

  85. #bzhdoc
    Topic

    Un chapitre par domaine de l'application

    Exemple :
    – Navigation,
    – Catalogue,
    – Recherche
    – Panier,
    – Checkout,
    – Mon Compte.

    View full-size slide

  86. Topic : sous-niveau

    Navigation :
    – Principes généraux (grille de navigation)
    – Construction des URLs
    – Fil d’Ariane
    – Voir aussi : SEO, Catalogue, Recherche
    #bzhdoc

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  90. Référence

    Autodoc !

    Liste des URLs pour les API
    #bzhdoc

    View full-size slide

  91. Bref.
    #bzhdoc

    View full-size slide

  92. Écrire
    #bzhdoc

    View full-size slide

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

    View full-size slide

  94. Écrire pour être lu.
    #bzhdoc

    View full-size slide

  95. Write the (good) doc
    Questions ?
    #bzhdoc

    View full-size slide