Índice

Tipos de documentação

Abaixo está um breve resumo dos tipos de contribuições de documentação aceitas em amp.dev:

Tutorial introdutório

Tutoriais introdutórios ajudam o desenvolvedor a compreender a ideia geral da tecnologia. Eles ajudam a começar a programar e terminam com um projeto básico "Hello World" completo. Tutoriais introdutórios demonstram como construir um recurso chave do AMP através de um processo passo-a-passo. Combine tutoriais introdutórios com exemplos de trechos de código ou um exemplo que possa ser baixado e necessite de alterações mínimas, por parte do desenvolvedor, para executar.

Exemplos amp.dev:

Faça	Não faça
Forneça ajuda com breves explicações e passos mínimos.	Aprofunde-se nas nuances do projeto. Pode haver muitas maneiras de alcançar os resultados do tutorial, mas a ideia não é mostrar todos os caminhos, mas apenas um único bom caminho.
Forneça um ambiente e ferramentas simples para configurar.	Assuma que o desenvolvedor tem familiaridade com o produto e habilidades de programação de nível elevado.
Mantenha o exemplo visualmente simples.	Complique em nome do estilo, a menos que o tutorial seja sobre estilo.
Forneça uma captura de tela de cada passo e demonstração finalizada.	Apenas forneça exemplos de código.
Crie um plano de ação. Indique aos desenvolvedores o que devem acompanhar.	Contraste o exemplo com explicações adicionais. Considere registrar um issue para um guia ou tutorial se você achar que não há acompanhamento suficiente.

Tutorial avançado

Tutoriais avançados ajudam os desenvolvedores a realizar uma tarefa específica. Ele assume que o desenvolvedor possui alguma familiaridade com o AMP. Deve demonstrar como construir uma experiência, integrar um recurso ou abordar tarefas de implementação.

Exemplos amp.dev:

Faça	Não faça
Forneça instruções passo-a-passo com um projeto final claro.	Forneça detalhes exaustivos e conceitos super-elaborados.
Forneça amostras de código ou código inicial para baixar. Adicionalmente, disponibilize para download o projeto final completo	Forneça exemplos alternativos ou o processo para alcançar o resultado final.
Crie um ambiente plug-and-play.	Forneça um link para um tutorial de configuração. Os tutoriais devem ser independentes.

Guia introdutório

Um guia introdutório fornece uma visão geral de informações relevantes para começar a usar o AMP. Ele deve identificar o recurso, descrever o que é e terminar com o que ele faz. Guias introdutórios introduzem um desenvolvedor aos requisitos básicos de um recurso sem direcioná-lo à sua implementação. Se você está acompanhando um processo passo-a-passo com amostras de código, você provavelmente está escrevendo um tutorial. Se você está descrevendo todos os elementos programáticos de um componente AMP, você está provavelmente escrevendo um documento de referência.

Exemplos amp.dev:

Faça	Não faça
Identifique o que o documento vai abordar.	Divida a solução em um processo passo-a-passo.
Introduza recursos e conceitos. Inclua links para documentos de referência para detalhes de uso avançado.	Descreva em detalhes.
Forneça amostras de código e exemplos do mundo real.	Crie uma aplicação inteira. Inclua links para exemplos ou demos em vez de explorar mais a fundo.
Cite usos e restrições técnicas.	Cite todos os usos técnicos possíveis e descreva como é feito.

Guia conceitual

Guias conceituais ajudam desenvolvedores a desenvolver um entendimento mais profundo do AMP. Um conceito é como um mapa topográfico. Ele mostra as várias trilhas em uma região com detalhes tais como alterações na altitude, mas não indica um trajeto específico através do terreno. Explique o que é um recurso e como ele funciona em vez de como construir um recurso.

Exemplos amp.dev:

Faça	Não faça
Forneça ao desenvolvedor todos os elementos necessários para que ele possa construir a solução.	Guie o desenvolvedor ativamente para um estado final específico.
Cubra todos os aspectos das áreas temáticas.	Concentre-se em uma tarefa específica.
Inclua recursos visuais, como diagramas ou capturas de tela.	Pense bem sobre isto. Você pode solicitar ajuda para recursos visuais do [grupo de trabalho de divulgação] (https://github.com/ampproject/wg-outreach).
Forneça amostras de código e links para outros guias.	Forneça um link de download para um projeto finalizado ou desvie o assunto.

Documentação de referência

Uma documentação de referência lista todos os elementos programáticos para um componente AMP. Ela fornece informações comportamentais detalhadas e foi projetada para ser lida superficialmente. Uma documentação de referência deve incluir exemplos de amostras de código e demonstrar casos de uso.

Os documentos de referência amp.dev são encontrados no catálogo de componentes AMP.

Contribuições para a documentação de referência do AMP são enviadas para o repositório AMPHTML.

Faça	Não faça
Use uma linguagem clara e concisa que explique como o componente funciona.	Explique um processo on construa um projeto.
Estruture com títulos, cabeçalhos e subtítulos fáceis de encontrar.	Agrupe o conteúdo em seções com nomes abstratos.
Forneça trechos de código que demonstrem o uso do componente.	Crie aplicações de demonstração completas.

Written by @CrystalOnScript