Contenido

Tipos de documentos

A continuación, se muestra un breve resumen sobre los tipos de documentos y las contribuciones que se aceptan en amp.dev:

Tutorial de introducción

Los tutoriales de introducción ayudan al desarrollador a comprender las ideas generales de la tecnología. Estos comienzan con los principios básicos de la programación y concluyen con un proyecto muy sencillo pero completo del tipo “Hola Mundo“. En los tutoriales de introducción se muestra cómo construir alguna de las funciones clave de AMP mediante un proceso donde se explica paso a paso. Utilice los tutoriales de introducción junto con ejemplos de los estilos integrados en el código y/o un ejemplo descargable donde el desarrollador necesite hacer cambios mínimos para ejecutarlos.

Ejemplos en amp.dev:

Qué hacer	Qué no hacer
Proporciona orientación con explicaciones breves y medidas mínimas.	Profundizar en los detalles del proyecto. Probablemente haya muchas formas de lograr el resultado que se indica el tutorial, sin embargo, el punto no es mostrar todas las rutas, sino solamente una pero que sea la mejor.
Proporciona un entorno simplificado y herramientas para configurarlo.	Suponer que el desarrollador está familiarizado con el producto y cuenta con una gran experiencia y habilidades en programación.
Hacer que el ejemplo se mantenga sencillo visualmente.	Complicar las cosas por cuestiones del estilo, a menos que el tutorial sea sobre el estilo.
Proporcionar una captura de pantalla con cada uno de los pasos y la demostración terminada.	Solo proporcionar ejemplos sobre el código.
Crear un llamado a la acción. Indicarle al desarrollador los procedimientos que debe seguir.	Combinar el ejemplo con una explicación más detallada. Considere crear una propuesta para una guía o tutorial si considera que no se le ha dado el seguimiento adecuado.

Tutorial avanzado

Los tutoriales avanzados ayudan a los desarrolladores a cumplir con tareas específicas. En ellos se da por hecho que el desarrollador está familiarizado con AMP. En este tipo de tutoriales debe mostrarse cómo construir una experiencia, integrar una función o solucionar tareas de implementación.

Ejemplos en amp.dev:

Qué hacer	Qué no hacer
Proporcionar instrucciones paso a paso con un proyecto final que esté bien establecido.	Proporcionar detalles muy minuciosos y conceptos excesivamente elaborados.
Proporcionar ejemplos del código o códigos de inicio descargables. Además, permitir que cuando el proyecto final esté completo pueda descargarse.	Proporcionar ejemplos o procesos alternativos para obtener el resultado final.
Crear un entorno que no necesite configuración y esté listo para usarse.	Crear un enlace hacia un tutorial de configuración. Los tutoriales deben ser independientes.

Guía de introducción

Una guía de introducción proporciona un resumen general sobre la información importante para comenzar a utilizar AMP. En la guía, debe identificarse la función, describir qué es y finalizar con lo que hace. Este tipo de guías introducen al desarrollador en los requisitos básicos de la función sin sugerirle que la implemente. Si está revisando un proceso paso a paso mediante ejemplos del código, probablemente esté escribiendo un tutorial. Si está describiendo todos los elementos de programación para un componente de AMP, seguramente está escribiendo un documento de referencia.

Ejemplos en amp.dev:

Qué hacer	Qué no hacer
Especificar la información que se incluirá en el documento.	Separar la información en un proceso paso a paso.
Presentar cuáles son las funciones y conceptos. Crear un enlace hacia los documentos de referencia para buscar información sobre el uso de funciones y conceptos avanzados.	Describir todo con excesivo detalle.
Proporcionar ejemplos del código y de su aplicación en la vida real.	Diseñar una aplicación completa. Crear un enlace hacia ejemplos o demostraciones en vez de analizarlos más detalladamente.
Hacer una lista con los usos técnicos y sus limitaciones.	Hacer una lista con todos los usos técnicos posibles e incluir la explicación sobre cómo se elaboró.

Guía de conceptos

Las guías de conceptos ayudan a los desarrolladores a comprender más profundamente cómo funciona AMP. Una guía conceptual es como un mapa topográfico. Muestra los diversos caminos de la zona con detalles como los cambios en la elevación, pero no establece una ruta específica a través del terreno. En resumen, explican qué es y cómo funciona una función en lugar de cómo construirla.

Ejemplos en amp.dev:

Qué hacer	Qué no hacer
Proporcionarle al desarrollador todos los elementos que necesite para construir una solución.	Guiar activamente al desarrollador hacia un objetivo final específico.
Cubrir todos los aspectos de los diversos temas.	Centrarse en una tarea específica.
Incluir recursos visuales, por ejemplo, diagramas o capturas de pantalla.	Pensar demasiado en esto, puede solicitar ayuda para incluir recursos visuales en el [grupo de trabajo para divulgación](https://github.com/ampproject/wg-outreach).
Proporcionar ejemplos de códigos y enlaces hacia otras guías.	Proporcionar un descargable hacia un proyecto finalizado o que no tenga relación con el tema.

Documentos de referencia

La documentación de referencia enumera todos los elementos de programación que conforman los componentes de AMP. Proporciona información detallada del comportamiento y está diseñada para poder escanearse. La documentación de referencia debe incluir buenos ejemplos de códigos y casos de uso.

Los documentos de referencia de amp.dev se encuentran en el catálogo de componentes de AMP.

La documentación de referencia de AMP contribuye al repositorio de AMPHTML.

Qué hacer	Qué no hacer
Utilizar un lenguaje claro y conciso para explicar cómo funcionan los componentes.	Explicar un proceso o crear un proyecto.
Estructurarlos con títulos, encabezados y subtítulos que puedan escanearse fácilmente.	Organizar el contenido utilizando nombres abstractos.
Proporcionar fragmentos del código que muestren el uso de los componentes.	Crear aplicaciones de demostración completas.

Written by @CrystalOnScript