SlideShare une entreprise Scribd logo
LA FONCTIONNALITÉ N’EXISTE PAS
SANS DOCUMENTATION
NO FEATURE
NO DOC
www.ez.nowww.ez.no
@sarahhaim
Bonjour
Sarah Haïm-Lubczanski
@sarahhaim
@mereteresa
● Technical Writer
● Canard en plastique
Photo by Tom Morris
www.ez.nowww.ez.no
@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 ?
www.ez.nowww.ez.no
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir,
expérience
+++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++
www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir,
expérience
+++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++
DE LA DOC
QUALITÉ
www.ez.nowww.ez.no
@sarahhaim
$> whatis doc$> whatis doc
Qu’est-ce qui fait partie de la doc ?
https://answergarden.ch/701736
www.ez.nowww.ez.no
@sarahhaim
●
README
●
Releases Notes
●
Best Practices
●
Code comments
doc générée→
$> whatis doc$> whatis doc
Qu’est-ce qui fait partie de la doc ?
https://answergarden.ch/701736
www.ez.nowww.ez.no
@sarahhaim
●
README
●
Releases Notes
●
Best Practices
●
Code comments
doc générée→
$> whatis doc$> whatis doc
Qu’est-ce qui fait partie de la doc ?
● Tutoriels
● Référence
● How-to, Cookbooks
● Guide, Concepts
https://answergarden.ch/701736
www.ez.nowww.ez.no
@sarahhaim
Comment mesurer la qualité d’une doc ?
Photo by epSos.de
www.ez.nowww.ez.no
@sarahhaim
Cohérence
● Texte, exemples, et images
www.ez.nowww.ez.no
@sarahhaim
Cohérence
● Texte, exemples, et images
https://docs.docker.com/engine/docker-overview/#docker-architecture
www.ez.nowww.ez.no
@sarahhaim
Clarté
● Navigation
● Accessibilité
● Utilisabilité
– Cf Opquast
https://checklists.opquast.com/
www.ez.nowww.ez.no
@sarahhaim
Clarté
● Navigation
● Accessibilité
● Utilisabilité
– Cf Opquast
https://checklists.opquast.com/
www.ez.nowww.ez.no
@sarahhaim
Liens sémantiques
● Recommandation de contenu
« ceci est en rapport »
www.ez.nowww.ez.no
@sarahhaim
Liens sémantiques
● Recommandation de contenu
« ceci est en rapport »
http://symfony.com/doc/current/controller.html
www.ez.nowww.ez.no
@sarahhaim
Fiabilité 
● Disponible
● Version consultée
● Date de mise à jour
www.ez.nowww.ez.no
@sarahhaim
Fiabilité 
● Disponible
● Version consultée
● Date de mise à jour
www.ez.nowww.ez.no
@sarahhaim
Qualité supérieure : langue natale
● Dans ma langue
www.ez.nowww.ez.no
@sarahhaim
Qualité supérieure : langue natale
● Dans ma langue
www.ez.nowww.ez.no
@sarahhaim
Qualité supérieure : offrir de l’aide
– Obtenir de l’aide
directe
– Contacter le
support
– Soumettre un bug
https://docs.djangoproject.com/fr/2.0/
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe
● « Google it »
– Codes erreurs : avoir une référence
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe
● « Google it »
– Codes erreurs : avoir une référence
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : feedbacks
● Feedback sur la doc et le produit
● Contributions
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : feedbacks
● Feedback sur la doc et le produit
● Contributions
http://httpd.apache.org/docs-project/
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : Troubleshooting
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : Troubleshooting
https://developer.twitter.com/en/docs/basics/things-every-developer-should-know
www.ez.nowww.ez.no
@sarahhaim
Qualité de luxe : Troubleshooting
www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++
www.ez.nowww.ez.no
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
DE LA DOC
QUOTIDIEN
www.ez.nowww.ez.no
@sarahhaim
Travailler sa documentation
● Créer la documentation
● Maintenir la doc
● Valoriser la doc
www.ez.nowww.ez.no
@sarahhaim
Que proposez-vous à vos utilisateurs ?
● Apprendre
● Résoudre des problèmes
– Installation
– Utilisation de la feature principale
– Utilisation des features expertes
www.ez.nowww.ez.no
@sarahhaim
Pourquoi écrire la doc ?
● Pour le futur
● Pour vos collaborateurs
– Collègues
– Clients
– Intégrateurs de votre produit
– Partenaires
– Contributeurs
● Pour obtenir des contributeurs
● Pour vous améliorer en écriture
www.ez.nowww.ez.no
@sarahhaim
Créer la documentation
● Partez des spécifcations fonctionnelles
● Deux rubriques :
– Installation
– Utilisation
www.ez.nowww.ez.no
@sarahhaim
Maintenir la doc ?
● Mettre à jour le contenu
● Y compris supprimer
● Utiliser des outils en rapport avec votre
besoin
www.ez.nowww.ez.no
@sarahhaim
Valoriser la doc ?
● 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
www.ez.nowww.ez.no
@sarahhaim
Effort marketing 
● Wording : utiliser les mêmes mots
● Interagir avec sa communauté
– Quels sont les diffcultés ?
– Qu’est-ce qui est attendu ?
● Analyses du trafc sur la doc
– Est-ce que les lecteurs vont à l’Etape 3 du
Tutoriel ?
www.ez.nowww.ez.no
@sarahhaim
Effort marketing 
● Wording : utiliser les mêmes mots
● Interagir avec sa communauté
– Quels sont les diffcultés ?
– Qu’est-ce qui est attendu ?
● Analyses du trafc sur la doc
– Est-ce que les lecteurs vont à l’Etape 3 du
Tutoriel ?
www.ez.nowww.ez.no
@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-gu
ide/
www.ez.nowww.ez.no
@sarahhaim
Orthographe et grammaire
● Français
– Synonymes: CRISCO
– Orthographe : Projet Voltaire
● Anglais
– Grammaire : Grammarly
– Expressions : Linguee
– Style : Hemingway App
www.ez.nowww.ez.no
@sarahhaim
Traduction collaborative
● Crowdin
www.ez.nowww.ez.no
@sarahhaim
Traduction collaborative
● Crowdin
www.ez.nowww.ez.no
@sarahhaim
Traduction par des robots
● DeepL : version payant = API
www.ez.nowww.ez.no
@sarahhaim
Traduction par des robots
● DeepL : version payant = API
www.ez.nowww.ez.no
@sarahhaim
Webmaster
● Et tous vos outils de Webmaster
– Logs
– Performances
– Etc.
www.ez.nowww.ez.no
@sarahhaim
Automatiser ?
● Oui mais...
● Processus de Release des fonctionnalités
www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++
www.ez.nowww.ez.no
@sarahhaim
POUR TOUT DE SUITE
DES IDÉES
www.ez.nowww.ez.no
@sarahhaim
Stop it right now !
● Private jokes
– Star Wars
– H2G2
– Même les Monty Python
● Ou alors...documentez-les !
https://docs.python.org/3.3/tutorial/controlflow.html#keyword-arguments
https://youtu.be/i5nSwRVR0sI
www.ez.nowww.ez.no
@sarahhaim
Stop à certains mots
● Niveau de langue trop recherché
● Langage trop générique
● Mots épicènes et inclusivité
– Bob et Alice
www.ez.nowww.ez.no
@sarahhaim
Stop les fautes d’orthographe
● Se relire
● Se faire relire
www.ez.nowww.ez.no
@sarahhaim
Stop les fautes d’orthographe
● Se relire
● Se faire relire
Pascal Borreli is
watching us
www.ez.nowww.ez.no
@sarahhaim
Stop les commentaires
● Commentaires utilisateurs sur la page
www.ez.nowww.ez.no
@sarahhaim
Stop les commentaires
● Commentaires utilisateurs sur la page
www.ez.nowww.ez.no
@sarahhaim
Commencez les tests
● Testez votre doc
● exemples :
– installation
– Faites vos recherches sur Stack Overfow
– Legacy et redirections
– Testez votre recherche interne
www.ez.nowww.ez.no
@sarahhaim
Commencez les tests
● Testez votre doc
● exemples :
– installation
– Faites vos recherches sur Stack Overfow
– Legacy et redirections
– Testez votre recherche interne
www.ez.nowww.ez.no
@sarahhaim
Commencez les peer reviews
● Faites des revues de la documentation
www.ez.nowww.ez.no
@sarahhaim
Commencez à ranger
● Vérifez 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
www.ez.nowww.ez.no
@sarahhaim
Source : Daniele Procida / @EvilDMP
www.ez.nowww.ez.no
@sarahhaim
Pour les gourmands, 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
www.ez.nowww.ez.no
@sarahhaim
Doudou Lib Pote Lib Shiny Lib
Savoir, expérience +++ + +
Se faire aider ++ +++ ++
Documentation
exhaustive
+ ++ +++
www.ez.nowww.ez.no
@sarahhaim
Photo by Seaman Apprentice Joshua Adam Nuzzo, U.S. Navy
www.ez.nowww.ez.no
@sarahhaim
No doc, no feature ?
● Faites une QA pour la doc aussi
● Efforts à fournir existent dans votre taille
● Commencez immédiatement !

Contenu connexe

Similaire à Sans documentation, la fonctionnalité n'existe pas !

Alphorm.com Formation Le langage Ruby
Alphorm.com Formation Le langage RubyAlphorm.com Formation Le langage Ruby
Alphorm.com Formation Le langage Ruby
Alphorm
 
De l'artisanat aux bases de l'industrialisation
De l'artisanat aux bases de l'industrialisationDe l'artisanat aux bases de l'industrialisation
De l'artisanat aux bases de l'industrialisation
Agnès Haasser
 
Conseils et outils gratuits pour démarrer
Conseils et outils gratuits pour démarrer Conseils et outils gratuits pour démarrer
Conseils et outils gratuits pour démarrer
Needeo
 
Supports de cours Fit4Digital future - CMS
Supports de cours Fit4Digital future - CMSSupports de cours Fit4Digital future - CMS
Supports de cours Fit4Digital future - CMS
Annabelle Buffart
 
Les liens d'autorité - Seocamp Toulouse
Les liens d'autorité - Seocamp Toulouse Les liens d'autorité - Seocamp Toulouse
Les liens d'autorité - Seocamp Toulouse
Sandrine Bertrand
 
Breizh campux
Breizh campuxBreizh campux
Breizh campux
Florence Herrou
 
De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...
De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...
De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...
Sébastien Prunier
 
Développer en mode kick-ass à Devoxx France
Développer en mode kick-ass à Devoxx FranceDévelopper en mode kick-ass à Devoxx France
Développer en mode kick-ass à Devoxx France
Samuel Le Berrigaud
 
Réaliser son film de A à Z, avec les moyens du bord
Réaliser son film de A à Z, avec les moyens du bordRéaliser son film de A à Z, avec les moyens du bord
Réaliser son film de A à Z, avec les moyens du bord
OpéProd Création Audiovisuelle
 
Coffre à outil pour les auteurs - Stratégie entonnoir
Coffre à outil pour les auteurs -  Stratégie entonnoirCoffre à outil pour les auteurs -  Stratégie entonnoir
Coffre à outil pour les auteurs - Stratégie entonnoir
Marie Bo
 
10 Slides à lire avant de commencer le développement Android
10 Slides à lire avant de commencer le développement Android10 Slides à lire avant de commencer le développement Android
10 Slides à lire avant de commencer le développement Android
Anthony Faucogney
 
Concevez votre site web avec php et mysql
Concevez votre site web avec php et mysqlConcevez votre site web avec php et mysql
Concevez votre site web avec php et mysql
José De Araùjo Fernandes
 

Similaire à Sans documentation, la fonctionnalité n'existe pas ! (12)

Alphorm.com Formation Le langage Ruby
Alphorm.com Formation Le langage RubyAlphorm.com Formation Le langage Ruby
Alphorm.com Formation Le langage Ruby
 
De l'artisanat aux bases de l'industrialisation
De l'artisanat aux bases de l'industrialisationDe l'artisanat aux bases de l'industrialisation
De l'artisanat aux bases de l'industrialisation
 
Conseils et outils gratuits pour démarrer
Conseils et outils gratuits pour démarrer Conseils et outils gratuits pour démarrer
Conseils et outils gratuits pour démarrer
 
Supports de cours Fit4Digital future - CMS
Supports de cours Fit4Digital future - CMSSupports de cours Fit4Digital future - CMS
Supports de cours Fit4Digital future - CMS
 
Les liens d'autorité - Seocamp Toulouse
Les liens d'autorité - Seocamp Toulouse Les liens d'autorité - Seocamp Toulouse
Les liens d'autorité - Seocamp Toulouse
 
Breizh campux
Breizh campuxBreizh campux
Breizh campux
 
De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...
De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...
De votre idée géniale à votre Minimum Viable Product - Café Techno Niort ...
 
Développer en mode kick-ass à Devoxx France
Développer en mode kick-ass à Devoxx FranceDévelopper en mode kick-ass à Devoxx France
Développer en mode kick-ass à Devoxx France
 
Réaliser son film de A à Z, avec les moyens du bord
Réaliser son film de A à Z, avec les moyens du bordRéaliser son film de A à Z, avec les moyens du bord
Réaliser son film de A à Z, avec les moyens du bord
 
Coffre à outil pour les auteurs - Stratégie entonnoir
Coffre à outil pour les auteurs -  Stratégie entonnoirCoffre à outil pour les auteurs -  Stratégie entonnoir
Coffre à outil pour les auteurs - Stratégie entonnoir
 
10 Slides à lire avant de commencer le développement Android
10 Slides à lire avant de commencer le développement Android10 Slides à lire avant de commencer le développement Android
10 Slides à lire avant de commencer le développement Android
 
Concevez votre site web avec php et mysql
Concevez votre site web avec php et mysqlConcevez votre site web avec php et mysql
Concevez votre site web avec php et mysql
 

Sans documentation, la fonctionnalité n'existe pas !