Voici la vidéo, les slides et surtout les liens complémentaires de la conférence que j’ai eu l’honneur d’animer au PHP Tour 2018 à Montpellier. J’avais intitulé ma session Sans documentation, la fonctionnalité n’existe pas ! et le titre avait déjà amené beaucoup de débats avec mes pairs. Je vous laisse donc m’écouter, me lire et, si le sujet vous intéresse, approfondir la question par vous-même.
La vidéo de la session
Les slides de « Sans documentation, la fonctionnalité n’existe pas »
J’ai pris soin de garder les animations, c’est pourquoi vous avez un grand nombre de diapos : quand il y a deux versions, c’est que j’ai gardé les versions avant et après l’animation.
-
Les liens complémentaires
Durant ma présentation, je cite des outils ou je référence le travail d’autres personnes, voici les liens complémentaires.
-
Ecrire de la doc
- Writing inclusive documentation | Google Developer Documentation Style Guide (en) : écrire pour toutes les personnes qui liront votre doc
- StaticGen : recherche de générateurs statiques opensource, on peut filtrer par licence, langage ou moteur de templates
- What nobody tells you about documentation (en): conférence sur comment organiser votre doc
- Documentation Guide :: Write the Docs (en) : la documentation de la documentation, c’est là que vous trouverez la base pour débuter
- beautiful-docs : des exemples de documentations réussies
- feedmereadmes, Free README editing (en) : soumettez votre README en review (+ des conseils pour écrire un excellent README)
-
Des outils pour l’écriture
- Asciidoctor (en) : outil pour écrire de la doc en texte
- Projet Voltaire (fr) : Règles d’orthographe et de grammaire
- CRISCO – Dictionnaire des synonymes (fr)
- Hemingway Editor (en) : évaluer le style de vos textes (en anglais)
- Grammarly(en) : extension navigateur pour corriger la syntaxe et la grammaire anglaise
- English translation avec Linguee : aide à la traduction d’expression pour éviter les barbarismes
- Crowdin : traduction collaborative, exemple « Translating eZ Platform to French language »
- DeepL Traducteur : robot traducteur, API disponible (payante)
-
De belles documentations
- eZ Platform Developer Documentation : mon travail
- Command reference :: Redis
- Documentation de Django
- Les concepts de Kubernetes
-
Un README pour toute doc, et ça suffit
-
Pour votre doc d’API
- Dredd, HTTP API Testing Framework : testez vos API depuis leur description
- Apiary API : la documentation de l’outil Apiary
-
Aller plus loin…
- Carolyn Stransky: Humanizing Your Documentation | JSConf Iceland 2018 (en) et les slides sur Speaker Deck
- Write in AsciiDoc, Publish Everywhere! (en)
- matiassingers/awesome-readme : liste maintenue de README réussis
- [DevFest Nantes 2017] Documentation as Code (fr) : avec un exemple d’utilisation d’ASCIIDoc
- Use Case Driven Documentation (en) : billet de blog de 2006, avec l’idée de partir des cas métiers pour construire la doc, par Tyner Blain
- How to write useful code documentation (en) : billet sur le site de Hewlett-Packard, par Steven Vaughan-Nichols
- RequireJS – An example of bad documentation (en) : critique de la doc de RequireJS par Ha-Duong Nguyen
- 14 Examples of Documentation Mistakes You Are Making (en) : billet de 2015, encore valide, sur des points à éviter dans la doc par Jonathan DeVore
-
Opensource et médias sociaux 