Introduction (EN)

Les tutoriels versus le guide

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 ?

Contributions aux tutoriels

Ce que nous attendons

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 concepts qui sont plus largement utilisables, avec les avertissements et restrictions inhérents à leurs utilisations.

Si vous êtes intéressé par l’idée de contribuer, vous pouvez ouvrir une issue sur le github sous le tag cookbook idea avec votre idée 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, merci de suivre le plan ci-dessous autant que possible. Certaines sections sont obligatoires, d’autres sont optionnelles. Suivre l’ordre chronologique est fortement conseillé mais non 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 exigeons que vous suiviez le plan ci-dessous. Cependant nous comprenons que parfois vous ayez besoin de vous en écarter pour conserver une certaine clarté dans vos explications. Malgré tout, chaque exemple doit à un certain moment discuter les raisons de l’utilisation du modèle proposé, de préférence dans la section des modèles alternatifs.

Exemple de base

obligatoire

  1. Exprimer le problème en une à deux phrases.
  2. Expliquer la plus simple solution en une à deux phrases.
  3. Montrer un court extrait de code.
  4. Expliquer ce que cela réalise en une phrase.

Détails sur le contenu

obligatoire

  1. Anticiper les questions que pourrait se poser une personne découvrant l’exemple. (les Blockquotes sont très bien pour ça)
  2. Mettre en avant les erreurs classiques et comment elles peuvent être évitées.
  3. Montrer de courts extraits de code de bon et mauvais patterns.
  4. Argumenter sur le fait que c’est un bon pattern. L’utilisation de liens et références n’est pas obligatoire mais conseillée.

Cas d’utilisation concret

obligatoire

Démontrer que le code répond à un cas d’utilisation commun ou intéressant soit en:

  1. détaillant quelques exemples simples ou
  2. en utilisant un exemple dans codepen/jsfiddle

Si vous choisissez le dernier, vous devrez quand même décrire ce que c’est et
ce que cela fait.

Contexte additionnel

optionnel

Il est toujours utile d’écrire au sujet de ce pattern, quand / où il doit s’appliquer, pourquoi c’est une bonne solution tout en illustrant avec des morceaux de code ou en présentant des sources de lectures additionnelles.

Quand éviter ce pattern

optionnel

Cette section n’est pas obligatoire mais fortement recommandée. 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 plupart 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.

Pattern alternatifs

obligatoire

Cette section est requise quand vous avez écrit une section sur la nécessité d’éviter ce pattern dans certains cas. Il est important d’explorer d’autres méthodes pour que les lecteurs ne soient pas laissés dans l’expectative, alors qu’ils ont pu lire que dans certains cas c’est un antipattern. Considérez que les utilisateurs ont différentes bases 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 essaient 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 implémentations alternatives. Une bonne liste de tutoriels fournit aux développeurs ce contexte.

Merci

Contribuer à de la documentation prend du temps et si vous prenez le temps de soumettre une PR à cette section de notre documentation, vous aurez toute notre gratitude.