La véritable histoire de toute documentation
c’est que personne ne sait comment bien faire
(et que c’est toujours le bordel au bout d’un moment)
- Chaîne documentaire
- Structuration de données
- Participation & Partage
💡
- Le code
- Les projets
- Les plateformes
- Les outils
→ Les communs
Au commencement était le manuel
Personne n’est obligé
d’utiliser votre produit
Doc minimale :
- Pré-requis
- Démarrage rapide
- Licence
- Contributions
- Support
Le basique : un README
Maintenance 🔫
- Abondance d’info
- Approche structurelle
- Risque important de décorrélation
Level Up : le wiki
Structure 🔫
- Séparation des contenus
- Cohésion / validation
Niveau Master Mind: le projet
🔫
- Curation des contenus
- Obsolescence
- Contribution
On s’attache trop à l’outil
Les bonnes questions™
- Qui accède au contenu ?
- Comment rechercher l’information ?
- Pourquoi contribuer ?
Le plus : la communauté
Le Guide du voyageur
Read The Fucking Manual
Tout sauf 🔫
- Inclusif
- Bienveillant
- Précis
Quand ai-je besoin
de la documentation ?
Je suis développeur (à la base)
J’ai tendance à découper les ensembles en sous-éléments simples pour comprendre leurs relations naturelles
Je suis biochimiste
Les choses sont plus claires et plus simples à retrouver quand elles sont rangées et classifiées selon des jeux de règles strictes
Je suis un créatif
Plus les choses sont visuelles, illustrées, plus elles sont simples à comprendre et à appliquer
L’accès à la doc
- Recherche
→ élément précis - Corpus
→ thématique dédiée - Lecture
→ linéaire progressive
La réponse ultime :
le livre de recettes !
📖
- Recettes : contenus textes et illustrations
→ pages de doc - Sommaire
→ lecture dirigée - Index
→ tags / recherche plein texte
💡 Structures
- Textes
- Illustrations
- Tags
💡 Primitives
- Navigation architecturée / dirigée
- Chapitrage
- Index
- Recherche plein texte
Les Quatre Fantastiques
Le manuel des Castors Juniors
- résoud tout
- toujours adapté
- répond à tous les adverbes interrogatifs
- où je trouve … ?
- comment je fais … ?
- quel est le … ?
- pourquoi … ?
Comment c’est possible ?
Vous allez devoir maintenir
4 documentations
1. README / Concepts
- Apprentissage
- Point de départ
- Orienté pratique
- Contenu rejouable à l’infini
- expliquer
- « Démarrer avec la plateforme »
- « Utiliser le module d’internationalisation »
- « Exécuter les tests »
- « Afficher les statistiques d’utilisation »
2. How-to
- Problèmes
- Recettes / point précis
- Dépendants du contexte
- Flexibles et adaptables
- démontrer
- « Comment activer le 2FA »
- « Comment configurer l’environnement de développement »
- « Comment installer manuellement des extensions »
- « Comment filtrer les requêtes entrantes »
3. Man pages
- Information
- Machinerie interne
- Structure projet (code, features, etc.)
- Contenus encyclopédiques
- résoudre,
explique les fondamentaux
NPM(1) NPM(1)
NAME
npm - javascript package manager
SYNOPSIS
npm [args]
VERSION
6.11.3
DESCRIPTION
npm is the package manager for the Node JavaScript platform. It puts
modules in place so that node can find them, and manages dependency con‐
flicts intelligently.
It is extremely configurable to support a wide variety of use cases.
Most commonly, it is used to publish, discover, install, and develop
node programs.
4. FAQs / Historique
- Compréhension
- Apporte du contexte
- Répond aux questions
sur le projet / features / etc. - Dogmatiques
- compromis
- « Puis-je ouvrir plusieurs comptes ? »
- « Pourquoi blacklister ce provider ? »
- « Quelles sont les limites d’espaces ? »
- « Quelles sont les versions disponibles ? »
De l’organicité des contenus
- On n’est pas des machines
- On a besoin d’une structure
- Industrialiser la création
Si on ne range pas,
c’est le bordel !
4×4
| README Porte d'entrée | Pratique | HOW-TO Recettes |
| Apprendre | Utiliser | |
| FAQs Discussions | Comprendre | MAN PAGES Encyclopédique |
C’est ça, le manuel
des Castors Juniors
Publier :
aux grands mots les bons outils
Deux objectifs
- Documentation accessible
- Contribution
Point d’entrée unique
- Format textuel léger
- Formatage simple
- Facile à prendre en main
- Facile à relire
- Markdown (Mmark)
- Asciidoc
- reStructuredText
- pandoc
Chaîne de production vers :
- Web (HTML)
- ePub
Vers le Web auto-hébergé
→ générateur statique
Vers le Web SaaS
→ Sphinx + ReadTheDocs
Vers PDF / ePub
→ Pandoc (ou LaTeX)
Contribution : dépôt de versions
- Suivi de versions
- Curation de contenus
(Pull / Merge Requests) - Participatif
Éditeurs en ligne avec Git
- Dillinger
- StackEdit
- Docsie
3 Questions
- Automatisation ?
- Internationalisation ?
- Bornage ?
Il n’y a pas de bon outil, ou de mauvais, il y a l’outil de votre cas d’usage
Plus de RTFM
Un guide rédactionnel
Incluez vos communautés
⚠
- 4×4
- Informez sur les bonnes pratiques
- Curation (bienveillante)
- Ne sur-estimez jamais le rôle de l’outil
Questions ?
Merci !
https://talks.m4dz.net/rewrite-the-docs/fr/ Disponible sous licence CC BY-SA 4.0
Illustrations
m4dz, CC BY-SA 4.0
Interleaf images
Courtesy of Unsplash and Pexels contributors
Icons
- Layout icons are from Entypo+
- Content icons are from FontAwesome
Fonts
- Cover Title: Sinzano
- Titles: Argentoratum
- Body: Mohave
- Code: Fira Code
Tools
Powered by Reveal.js
Source code available at
https://git.madslab.net/talks