Types de documentation
Voici un bref aperçu des types de contributions à la documentation acceptées sur amp.dev :
- Tutoriel d'introduction
- Tutoriel avancé
- Guide d'introduction
- Guide de concept
- Documentation de référence
Tutoriel d'introduction
Les tutoriels d'introduction aident le développeur à comprendre l'idée générale de la technologie. Ils commencent par une introduction au codage et se terminent par un projet de base complet « Premiers pas ». Les tutoriels d'introduction montrent comment créer une fonctionnalité clé d'AMP dans un processus étape par étape. Combinez les tutoriels d'introduction à des exemples de code intégré et/ou à un échantillon téléchargeable qui nécessite un minimum d'ajustements par le développeur pour s'exécuter.
exemples amp.dev :
| À faire | À éviter |
| Fournir des conseils avec de brèves explications et des étapes minimales. | Aller en profondeur dans les nuances du projet. Il peut exister plusieurs moyens pour parvenir au résultat du tutoriel, mais le but n'est pas de montrer tous ces moyens, mais un seul qui soit bon. |
| Fournir un environnement simplifié et des outils pour la configuration. | Supposer que le développeur est maîtrise le produit et a une capacité de codage d'expert. |
| S'assurer que l'échantillon est simpliste à vue d'œil. | Compliquer pour des raisons de style, à moins que le tutoriel porte sur le style. |
| Fournir une capture d'écran de chaque étape et de la démo finale. | Fournir uniquement des exemples de code. |
| Créer un appel à l'action. Indiquez au développeur ce qu'il doit suivre. | Combiner l'exemple avec des explications supplémentaires. Envisagez d'ouvrir un ticket pour un guide ou un tutoriel si vous trouvez le suivi insuffisant. |
Tutoriel avancé
Les tutoriels avancés aident les développeurs à accomplir une tâche spécifique. Cela suppose que le développeur maîtrise plus ou moins AMP. Ces tutoriels doivent montrer comment créer une expérience, intégrer une fonctionnalité ou effectuer des tâches de mise en œuvre.
exemples amp.dev :
- Comment configurer des analyses basiques pour vos pages AMP
- Ajouter un JavaScript personnalisé aux pages AMP avec amp-script
- Transformer votre site AMP en PWA
| À faire | À éviter |
| Fournir des instructions étape par étape avec un projet final clair. | Fournir des détails exhaustifs et des concepts trop élaborés. |
| Fournir des exemples de code ou un code téléchargeable pour débutant. De plus, rendez le projet final et complet téléchargeable. | Fournir des exemples ou des processus alternatifs pour atteindre le résultat final. |
| Créer un environnement plug and play. | Lien vers un tutoriel de configuration. Les tutoriels doivent être autonomes. |
Guide d'introduction
Un guide d'introduction donne un aperçu des informations pertinentes pour se lancer dans AMP. Il doit identifier une fonctionnalité, la décrire et dire enfin ce qu'elle fait. Les guides d'introduction présentent au développeur les exigences de base de la fonctionnalité sans lui demander de l'implémenter. Si vous parcourez un processus étape par étape avec des exemples de code, vous écrivez probablement un tutoriel. Si vous décrivez tous les éléments de programmation d'un composant AMP, vous écrivez probablement un document de référence.
exemples amp.dev :
| À faire | À éviter |
| Identifier ce dont traitera le document. | Décomposer en un processus étape par étape. |
| Présenter les fonctionnalités et les concepts. Lien vers des documents de référence pour des détails d'utilisation avancés. | Décrire en détail. |
| Fournir des exemples de code et des exemples réels. | Créer une application complète. Lien vers des exemples ou des démos à la place pour une exploration plus approfondie. |
| Énumérer les utilisations et les contraintes techniques. | Énumérer toutes les utilisations techniques possibles et la manière dont elles sont réalisées. |
Guide de concept
Les guides de concept aident les développeurs à approfondir leur compréhension d'AMP. Un guide de concept est semblable à une carte topographique. Elle montre les différents sentiers de la région avec des détails tels que les changements d'altitude, mais il ne prescrit pas un itinéraire spécifique pour traverser la zone. Expliquez ce qu'est une fonctionnalité et comment elle fonctionne plutôt que comment en créer une.
exemples amp.dev :
| À faire | À éviter |
| Fournir au développeur tous les éléments nécessaires à la construction d'une solution. | Guider activement le développeur vers un état final spécifique. |
| Couvrir tous les aspects des sujets. | Concentration sur une tâche spécifique. |
| Inclure des aides visuelles, telles que des diagrammes ou des captures d'écran. | Sinon, vous pouvez demander de l'aide pour les aides visuelles auprès du [groupe de travail Outreach] (https://github.com/ampproject/wg-outreach). |
| Fournir des exemples de code et créer des liens vers d'autres guides. | Fournir un lien de téléchargement vers un projet terminé ou un sujet éloigné. |
Documentation de référence
La documentation de référence répertorie tous les éléments de programmation d'un composant AMP. Elle fournit des informations comportementales détaillées et est conçue pour la numérisation. La documentation de référence doit inclure des exemples de code et démontrer les cas d'utilisation.
Les documents de référence amp.dev sont disponibles sous le catalogue de composants AMP.
| À faire | À éviter |
| Utiliser un langage clair et concis qui explique le fonctionnement du composant. | Expliquer un processus ou créer un projet. |
| Structure avec des titres, des grands titres et des sous-titres faciles à numériser. | Contenu de groupe sous des noms abstraits. |
| Fournir des extraits de code qui illustrent l'utilisation des composants. | Créer des applications de démonstration complètes. |
-