| title | type | order |
|---|---|---|
Introduction (EN) |
cookbook |
0 |
Cette page est en cours de traduction. Pour nous aider, vous pouvez participer sur le dépôt GitHub dédié de Vuejs-FR.
En quoi les tutoriels sont-ils différents du guide ? Pourquoi est-ce nécessaire ?
-
Plus focalisé : Dans le guide, nous racontons essentiellement une histoire. Chaque section se construit sur la base des précédentes et présume la connaissance de celles-ci. Dans les tutoriels, chaque tutoriel peut et devrait se suffire à lui-même. Cela signifie que les tutoriels peuvent se focaliser sur un aspect spécifique de Vue, plutôt que d'avoir à donner un aperçu global.
-
Plus de profondeur : Pour éviter de rendre le guide trop long, nous essayons d'inclure seulement les exemples les plus simples possible pour vous aider à comprendre chaque fonctionnalité. Puis nous passons à autre chose. Dans les tutoriels, nous pouvons inclure des exemples plus complexes, combinant les fonctionnalités de façon intéressante. Chaque tutoriel peut être aussi long et détaillé que besoin, afin de pleinement explorer son sujet.
-
Enseigner JavaScript : Dans le guide, nous supposons que le lecteur est au moins moyennement familier avec la norme ES5 de JavaScript. Par exemple, nous n'expliquerons pas comment
Array.prototype.filterfonctionne au sein d'une propriété calculée qui filtre une liste. Dans les tutoriels en revanche, des fonctionnalités essentielles de JavaScript (y-compris ES6/2015+) peuvent être explorées et expliquées pour montrer comment elles nous aident à construire de meilleures applications Vue. -
Explorer l'écosystème : Pour les fonctionnalités avancées, nous supposons que le lecteur a quelques connaissances sur l'écosystème. Par exemple, si vous voulez utiliser des composants monofichiers avec webpack, nous n'expliquerons pas comment configurer les parties qui ne concernent pas Vue dans la configuration de webpack. Dans les tutoriels, nous avons l'espace suffisant pour explorer plus en profondeur ces bibliothèques de l'écosystème - au moins dans la mesure où cela est universellement utile aux développeurs Vue.
Les tutoriels apportent aux développeurs des exemples à utiliser pour couvrir des cas d'utilisation courants ou intéressants et expliquent progressivement des points plus complexes. Notre but est d'aller au delà d'un simple exemple d'introduction et de mettre en avant des conceptes qui sont généralement utilisables avec les avertissements et les restrictions inhérants à leurs utilisations.
Si vous êtes interessé par l'idée de contribuer, vous pouvez ouvrir une requête sur le github sous le tag cookbook idea avec le concept que vous voulez mettre en avant afin que nous puissions vous guider dans la création d'une pull request qui sera acceptée. Après que votre idée ait été validée, il vous faudra suivre le plan ci-dessous autant que possible. Certaines sections sont obligatoires, d'autres sont optionnelles. Il est fortement conseillé de suivre l'ordre imposé même si ce n'est pas obligatoire.
Les tutoriels doivent généralement :
- Résoudre un problème spécifique et commun
- Commencer avec l'exemple le plus simple possible
- Introduire une complexité à la fois
- Comporter des liens vers d'autres sections de la documentation, plutôt que de réexpliquer les concepts
- Décrire le problème plutôt que de supposer que le lecteur est familier avec
- Expliquer le processus au-delà du simple résultat final
- Expliquer le pour et le contre de votre approche, en indiquant dans quels cas elle est appropriée ou non
- Mentionner des solutions alternatives si c'est pertinent, mais garder les explications en profondeur pour une autre recette.
Nous attendons à ce que vous suiviez le plan ci-dessous. Nous comprenons, cependant, qu'il puisse arriver que vous ressentiez la nécessité d'en déviez pour conserver une certaine clarté dans vos explications. Dans tous les cas, tous les exemples, doivent à un certain momment mettre en avant ce qu'implique l'utilisation du modèle qu'ils illustrent et cela préférablement dans la section des modèles alternatifs.
obligatoire
- Exprimer le problème en une à deux phrases.
- Expliquer la plus simple solution en une à deux phrases.
- Montrer un court extrait de code.
- Expliquer ce que cela réalise en une phrase.
obligatoire
- Anticiper les questions que pourrait se poser une personne découvrant l'exemple. (les Blockquotes sont très bien pour ça)
- Mettre en avant les erreurs classiques et comment elles peuvent être évitées.
- Montrer de courts extraits de code de bon et mauvais pattern.
- Argument sur le fait que c'est un bon pattern. L'utilisation de liens et références n'est pas obligatoires mais conseillée.
obligatoire
Démontrer que le code répond à un cas d'utilisation commun ou intéressant soit en:
- détaillant quelques exemples simples ou
- en utilisant un exemple dans codepen/jsfiddle
Si vous choisissez le dernier, vous devrez quand même décricre ce que c'est et ce que cela fait.
optionnel
Il est extrèmement utile de décrire à propos de ce pattern, quand/ ou il doit s'appliquer, pourquoi c'est une bonne solution tout en proprosant des parties de code en illustration ou en présentant des sources de lectures additionnelles.
optionnel
L'ajout de cette section n'est pas obligatoire mais fortement recommandé. Il n'y a pas lieu de l'écrire pour des cas simples comme le changement de classes basées sur un changement d'état mais pour des patterns plus avancés comme les "mixins", cela s'impose. La réponse pour la pluspart des questions sur le développement est "Cela dépend!", c'est le rôle de cette section. C'est ici que l'on va regarder objectivement quand ce pattern est utile, quand il doit être évité ou tout autre chose plus utile.
obligatoire
Cette section est obligatoire quand vous avez écrit une section sur la nécessité d'évité ce pattern dans certains cas. Il est important de mettre en avant d'autres moyens que ce pattern quand les lecteurs se sont vu dire que ce dernier est un antipattern dans certaines situations afin de ne pas les laisser sans ressources. Ce faisaint, considérez que les utilisateurs ont différentes base de code et qu'ils résolvent différents problèmes. Est-ce que l'application est grosse ou petite? Intègrent-ils Vue dans un projet existant, ou est ce qu'ils construisent leur application à partir de rien? Est ce que leurs utilisateurs essayent de résoudre un problème ou plusieurs? Y a t-il beaucoup de données asynchrones? Toutes ces considérations vont avoir un impact sur les implementations alternatives. Une bonnes liste de tutoriels fournis aux développeurs ce contexte.
Contribuer à de la documentation prend du temps et si vous prenez le temps de soumettre une PR à cette section de notre docmentation, vous aurez toute notre gratitude.