Lisez la documentation comme un livre

Je pensais que lorsque je travaillais pour de plus grandes entreprises technologiques, ce serait différent. Vous êtes légitimement dans le top 1% si vous RTFM
- @Ryan_Magoon

Une de mes croyances de longue date est que la chose la plus facile que vous puissiez faire pour faire avancer votre carrière est de vous asseoir avec la documentation de votre outil préféré et de la lire d'un bout à l'autre. De la première à la dernière page, comme un livre.

YouTube est super.

Les formations sont super.

Les articles de blog sont super.

Mais tout cela sert un but fondamentalement différent de la lecture directe de la documentation.

Lire la documentation augmente l'efficacité de toutes les choses énumérées ci-dessus. C'est fondamentalement différent, et c'est un multiplicateur de force.

Vous pourriez penser qu'il n'y a aucun moyen que vous puissiez vous rappeler de tout dans la documentation de toute façon, alors pourquoi s'embêter ? Le but de lire la documentation d'un bout à l'autre n'est en fait pas pour vous rappeler tout, vous pouvez donc vous libérer de cette pression !

Dans mon expérience, la lecture de la documentation offre deux avantages principaux :

• elle établit une carte mentale du territoire

• elle prépare votre subconscient

Établir une carte mentale

Une réfutation courante de la lecture de la documentation est qu'il est plus facile et plus efficace de simplement chercher des problèmes lorsque vous les avez.

Rechercher des solutions au fur et à mesure que vous avez des problèmes est génial ! Cela ne fonctionne cependant que pour des problèmes spécifiques et distincts. Habituellement, cela signifie des problèmes avec des messages d'erreur attachés ou des problèmes sous la forme de "Comment faire [x] chose dans [y] framework ?"

Ce sont les problèmes que vous savez que vous avez.

Il existe un autre ensemble de problèmes que vous ne savez même pas que vous avez. C'est ce que résout la lecture de la documentation.

Il y a des fonctionnalités dont vous ne connaissiez pas l'existence.

Vous réinventez des choses qui sont intégrées au langage ou à l'outil.

Certaines optimisations vous sont disponibles gratuitement et vous ne le saviez même pas.

En lisant la documentation, votre esprit génère une carte, la peuplant de repères.

Vous pouvez apprendre que MySQL a un support robuste pour les documents JSON, y compris l'indexation, en lisant la documentation. C'est génial, mais vous n'avez pas besoin de vous rappeler comment fonctionne l'indexation JSON ! Tout ce dont vous avez besoin de vous rappeler, c'est la notion la plus vague selon laquelle MySQL a une sorte de support JSON. La prochaine fois que vous rencontrerez un problème de performances JSON dans MySQL, vous penserez : "hé... j'ai lu quelque chose à ce sujet. Laisse-moi vérifier à nouveau."

C'est le résultat souhaité. Juste ça !

Lorsque vous avez une race condition dans votre application Laravel, une partie de votre cerveau s'illuminera et vous chuchotera "atomic locks". Ensuite, vous pourrez retourner à la documentation avec un problème discret à l'esprit et plonger dans les détails.

Plonger dans les détails

Lorsque vous plongerez dans les détails, vous irez beaucoup plus rapidement en profondeur, en raison de votre base de connaissances étendue. Avoir une vue plus large vous permet de faire des liens et des inférences dans l'ensemble du projet.

Les parties de la documentation qui ne s'appliquent pas directement à ce que vous faites maintenant ne font que peupler la carte mentale, ce qui sera utile plus tard. Cependant, il y a des parties de la documentation qui s'appliquent à ce que vous faites en ce moment !

Lorsque vous arrivez à une section de la documentation qui concerne votre champ de travail actuel, votre cerveau dessinera cette partie de la carte avec détail car vous êtes déjà imprégné du contexte. Vous obtiendrez beaucoup plus de valeur de cette section parce que vous êtes déjà familier avec le terrain, et maintenant vous remplissez tous les petits détails.

ChatGPT a la réponse

Oui, mais non, parce que malheureusement, vous devez encore savoir quelle est la question.

Si vous ignorez l'existence d'un sujet, comment le ferez-vous ressortir de GPT ? Les inconnus inconnus posent encore un problème ! Vous ne savez pas ce que vous ne savez pas.

Une fois que vous connaissez l'univers des sujets, vous pouvez utiliser GPT pour approfondir des aspects spécifiques. (Que ce soit une bonne idée ou non est un sujet pourrait être un autre article. Je pense que c'est surtout le cas !)

La carte est essentielle, mais il y a un bénéfice secondaire et sous-estimé de lire la documentation d'un bout à l'autre, et cela a à voir avec la manière dont votre cerveau traite l'information.

Préparer votre subconscient

Le système d'activation réticulaire (SAR) est un réseau de neurones dans le tronc cérébral qui filtre le bruit des informations. C'est la raison pour laquelle vous pouvez entendre votre nom clairement lorsqu'il est prononcé doucement dans une pièce bruyante. Votre nom est une information importante, donc votre cerveau y est attentif.

Avez-vous déjà appris un nouveau mot, et ensuite, il semble que ce mot apparaisse partout la semaine suivante ? C'est le SAR ! Le mot était auparavant du bruit, totalement filtré. Maintenant, c'est un signal, car vous venez de l'apprendre. Il a maintenant une signification.

Avez-vous déjà acheté une nouvelle voiture, disons que c'est un Jeep, et ensuite remarqué que d'une manière ou d'une autre, chaque voiture dans le monde est un Jeep ? Bien sûr, le nombre de Jeeps n'a pas changé. Vous n'en aviez tout simplement rien à faire. Votre cerveau est bombardé de marques et de modèles de véhicules toute la journée, tous les jours, donc il les filtre simplement. Mais lorsque vous obtenez un Jeep, il devient un signal important pendant un petit moment.

Lire la documentation remplit absolument votre cerveau de nouveau signal. Vous ne comprenez peut-être pas tous les détails, mais ce n'est pas grave ! Votre cerveau est maintenant réglé sur un tout nouvel univers d'informations qui vous passaient auparavant, indétectées.

Lorsque vous faites défiler Twitter et que vous voyez un conseil ou une astuce que vous auriez pu manquer auparavant, votre cerveau se réveille et dit : "Hé ! Ces mots me semblent familiers ! J'ai vu des mots comme ça auparavant !"

Si vous me demandiez de faire défiler Medical Twitter ou Law Twitter pendant une journée entière et de vous donner mes conclusions, je ne suis pas sûr que je pourrais en tirer quelque chose. Mon cerveau n'a tout simplement aucun contexte pour les choses qu'ils tweetent. Tout cela ressemble à du bruit pour moi. Il n'y a pas de seau, pas de fente pour que l'information passe, alors elle tombe directement.

Lire la documentation donne à votre cerveau un nouveau contexte, de nouveaux seaux pour attraper l'information. Il tisse les premiers brins d'une toile pour attraper des connaissances qui étaient là depuis toujours, qui vous passaient juste à côté.

Tout devient plus rentable ! Les podcasts, les articles de blog, les conversations avec les collègues, les commentaires sur Hacker News, les cours, YouTube, les messages d'erreur. Il y a plus de chances que quelque chose que vous lisez ou entendez se colle à l'un des brins.

Lire la documentation prépare votre cerveau à attraper plus de détails plus tard.

Comment lire la documentation

Je préfère les lire sur papier. J'ai fait imprimer et relié deux chapitres de la documentation MySQL et les ai lus.

Le support est à votre choix, mais les lire sans aucune pression pour se souvenir de quoi que ce soit est la clé. Votre cerveau fera le travail difficile. Si vous vous mettez trop de pression pour mémoriser tout, vous ne commencerez probablement même pas.

J'aime les lire et surligner tout ce qui me fait dire, "hein, génial !" et puis je continue. S'il y a de grandes sections qui deviennent super ennuyeuses, je commence à les survoler.

Lisez-les d'une traite, ou pas. Lisez quelques pages pendant quelques minutes chaque jour, et vous serez bientôt la personne la plus informée de votre équipe, peut-être de toute votre entreprise.

Des livres réputés peuvent remplacer les cas où la documentation fait littéralement des milliers de pages. J'ai lu plusieurs bons livres sur MySQL, PHP, Javascript, Python, Go et j’en passe, puis j'ai imprimé quelques-uns des chapitres les plus importants de la documentation. Même si ces chapitres faisaient plusieurs centaines de pages. J'ai feuilleté chaque page mais je n'ai pas lu chaque mot sur chaque page ! Plus vous lisez de la documentation réelle, mieux c'est.

Lire la documentation est égoïste

Je peux tweeter et bloguer autant que je veux sur le fait que lire la documentation est bon, et pourtant, très peu de gens la liront. Beaucoup de gens me disent souvent "Je n'ai pas le temps" ou "Je ne suis pas payé pour lire la documentation."

Je comprends totalement. Le temps est précieux.

Ma réponse est simple : lire la documentation est purement une poursuite d'intérêts personnels, et je peux toujours trouver le temps de faire des choses qui rendent ma vie meilleure.

Je veux faire mieux et plus rapidement mon travail. Je veux être promu. Je veux être mieux payé. Je veux être embauché. Je veux créer un meilleur contenu. Je veux que les gens me considèrent comme un expert. Je veux la satisfaction profonde de la maîtrise.

Je veux avancer, donc je lis la documentation. La plupart des gens ne le feront pas. Mais c'est ce qui rend les avantages relatifs efficaces !

Certaines personnes le feront, mais la plupart ne le feront pas.

Merci de m’avoir lu !