Développeurs : Comment (bien) Lire une Documentation ?
Les documentations de technos web (frameworks, langages...) sont souvent délaissées au profits de tutos par les développeurs juniors. Une erreur que vous ne ferez plus après avoir lu cet article.
5 min
Il n’est pas rare de voir des développeurs juniors se détourner de la documentation officielle d’un framework, d’un langage ou d’une techno au profit de tutos, pour une raison simple : ils ne savent pas la lire. L’objectif de cet article est de vous aiguiller dans la lecture d’une documentation, une compétence bien trop négligée lors de l’apprentissage du dev web.
Pourquoi les développeurs juniors n’aiment pas les documentations ?
Lorsqu’on commence à se former à un langage, une librairie ou encore un framework, la documentation qui est censée être notre meilleure alliée est, souvent à tort, considérée comme notre bête noire.
Les raisons sont principalement :
- La densité d’informations : la documentation vous délivre 100% de connaissance sur une techno, alors que bien souvent, 20% suffisent pour en maîtriser les mécaniques de base.
- La structuration du contenu : il ne faut pas longtemps à un développeur junior pour se perdre dans ce vaste océan d’informations en cherchant une information.
- L’aspect théorique : une documentation délivre des concepts, des généralités, là où un tuto vous donne des preuves concrètes, vous rassure. Le fameux : « Je n’ai qu’à faire pareil, ça va marcher ».
Bref, une doc, c’est du contenu au premier abord abondant, théorique et peu accessible… voilà de bons arguments pour se réfugier sur un tutoriel YouTube.
Et si on considérait le problème au lieu de le contourner ? Une documentation est bien plus riche que n’importe quelle autre ressource. Pourquoi ?
- Elle est écrite par ceux qui ont développé la techno
- Elle est complète
Apprendre à lire une documentation constitue un vrai apprentissage, bien trop souvent négligé dans les formations au développement web.
Cet article est consacré à la clarification des rubriques clés que l’on retrouve dans la plupart des documentations afin vous orienter dans ce vaste océan d’informations.
Les grandes rubriques d’une documentation
Dans la jungle des documentations, il est essentiel de comprendre la structure générale pour naviguer efficacement. Voici un tour d’horizon des sections les plus courantes que l’on retrouve dans la plupart des documentations.
📜 Introduction/Overview
Cette section pose les bases en présentant le contexte et les objectifs de la technologie que vous explorez.
Elle vous offre une vue d’ensemble pour comprendre où vous mettez les pieds.
🚀 Installation/Getting Started
Imaginez cette partie comme votre notice pour démarrer.
Elle vous guide pas à pas pour installer, initialiser, configurer la technologie sur votre machine, afin que vous puissiez commencer à explorer ses fonctionnalités.
✅ Guides
Le guide est là pour vous apprendre les fondamentaux.
Ici, vous découvrirez les fonctionnalités de base de la technologie. Elles représentent souvent 20% de ses capacités mais vous permettent d’accomplir 80% des tâches courantes.
Ne sous-estimez pas cette section, elle regorge de conseils et de bonnes pratiques.
👉 Exemples/Tutoriels
Souvent nommée « Playground », cette rubrique rassemble des exemples concrets d’utilisation de la techno et permet généralement d’interagir avec.
C’est l’endroit idéal pour expérimenter et comprendre comment appliquer ce que vous avez appris.
📚 API Reference
Si vous avez besoin de connaître les détails techniques d’un élément en particulier, cette section est cruciale.
Vous y trouverez une référence complète de tous éléments disponibles dans la technologie :
- Fonctions
- Classes
- Méthodes
- Propriétés
- Etc.
⚙️ Configuration
Une fois que vous maîtrisez les bases, vous voudrez peut-être personnaliser la technologie selon vos besoins.
Cette section dédiée à la configuration de la technologie vous montre comment adapter les réglages pour correspondre à votre projet.
🙋♂️ FAQ / Communauté
Vous n’êtes pas seul face aux difficultés !
Les docs proposent généralement soit :
- Une FAQ, dans laquelle sont livrées les réponses aux questions et problématiques les plus fréquemment posées.
- Un espace communautaire d’échange et de partage d’expériences.
🔄 Changelog
Les choses évoluent rapidement dans le monde de la technologie.
Cette section vous tient informé des nouveautés et des changements entre les différentes versions, vous aidant à rester à jour et à comprendre les éventuelles modifications qui pourraient affecter votre travail.
J’apprends une nouvelle techno : bien lire la doc
Maintenant que vous comprenez la structure générale d’une documentation, voici comment l’aborder efficacement à différentes étapes de votre apprentissage :
Démarrage
Les premiers pas avec une technologie se font généralement en consultant les rubriques suivantes :
- 📜 Introduction/Overview : Commencez par ici pour avoir une vision globale de la technologie.
- 🚀 Installation/Getting Started : Suivez les instructions pour configurer votre environnement de développement.
- ✅ Guides : Explorez les notions de base pour vous familiariser avec la technologie.
- 👉 Exemples/Tutoriels (optionnel) : Expérimentez, si vous le souhaitez, avec des exemples concrets pour mieux comprendre son fonctionnement.
Tout au long du développement (perfectionnement)
Une fois les bases assimilées, consultez la documentation tout au long de votre processus de développement lorsque vous rencontrez des problématiques.
- Besoin de configurer la technologie ? Consultez la section dédiée à la configuration.
- Besoin de détails techniques à propos d’une fonction spécifique ? Référez-vous à l’API Reference pour les détails techniques.
- Rencontre de problèmes spécifiques ? Explorez la FAQ ou consultez la communauté pour obtenir de l’aide.
- Mises à jour ou questions sur les changements ? Les Changelogs sont là pour vous informer.
Plus vous vous familiariserez avec la lecture des documentations, plus vous deviendrez efficace dans l’exploration et l’utilisation de nouvelles technologies.