Documentation types

Below is a brief outline of the types of documentation contributions accepted on amp.dev:

Introductory tutorial

Introductory tutorials help the developer understand the general idea of the technology. It starts them off coding and ends with a complete basic “Hello World” project. Introductory tutorials demonstrate how to build a key feature of AMP in a step-by-step process. Pair Introductory tutorials with inline code samples and/or a downloadable sample that requires minimal tweaks by the developer to run.

amp.dev examples:

Do	Don’t
Provide guidance with brief explanations and minimal steps.	Dive deep into project nuances. There may be many was to accomplish the outcome of the tutorial, but the point isn't to show every route, but a single, good route.
Provide a simplified environment and tools to setup.	Assume the developer has familiarity with product and expert level coding ability.
Keep sample visually simplistic.	Complicate for style sake, unless the tutorial is about styling.
Provide a screenshot of each step and finished demo.	Only provide code samples.
Create a call to action. Point the developer to what they should follow up with.	Conflate the example with further explanation. Consider opening an issue for a guide or tutorial if you feel there isn’t sufficient follow-up.

Advanced tutorial

Advanced tutorials help developers accomplish a specific task. It assumes the developer has some familiarity with AMP. It should demonstrate how to build an experience, integrate a feature, or address implementation tasks.

amp.dev examples:

Do	Don’t
Provide step-by-step instructions with a clear end project.	Provide exhaustive details and overelaborate concepts.
Provide code samples or downloadable starter code. Additionally, make the final and complete project downloadable.	Provide alternative examples or process to reach the end result.
Create a plug and play environment.	Link out to a set-up tutorial. Tutorials should be self contained.

Introductory guide

An introductory guide provides an overview of relevant information to get started with AMP. It should identify the feature, describe what it is, and finish with what it does. Introductory guides introduce a developer to the basic requirements of the feature without directing them to implement it. If you’re walking through a process step by step with code samples, you’re probably writing a tutorial. If you're outlining all the programmatic elements for an AMP component, you're probably writing a reference document.

amp.dev examples: - AMP email fundamentals - Common element attributes

Do	Don’t
Identify what the document will cover.	Break down into a step-by-step process.
Introduce features and concepts. Link to reference docs for advanced usage details.	Describe in exhaustive detail.
Provide code samples and real-world examples.	Create an entire app. Link to examples or demos instead for further exploration.
List technical uses and restraints.	List every possible technical use and how it’s done.

Concept guide

Concept guides help developers build a deeper understanding of AMP. A concept guide is like a topographic map. It shows the various trails in the area with details such as elevation changes, but it doesn’t prescribe a specific route through the terrain. Explain what a feature is and how it functions rather than how to build a feature.

amp.dev examples:

Do	Don’t
Provide the developer with all the elements needed to construct a solution.	Actively guide the developer to specific end state.
Cover all aspects of the subject areas.	Focus on a specific task.
Include visual aids, such as diagrams or screenshots.	Overthink this, you can request help for visual aids from the [outreach working group](https://github.com/ampproject/wg-outreach).
Provide code samples and link out to other guides.	Provide a download to a finished project or stray off topic.

Reference documentation

Reference documentation lists all the programmatic elements for an AMP component. It provides detailed behavioral information and is designed for scanning. Reference documentation should include exemplary code samples and demonstrate use-cases.

amp.dev reference documents are found under the AMP component catalogue.

AMP reference documentation is contributed to the AMPHTML repository.

Do	Don’t
Use clear and concise language that explains how the component works.	Explain a process or build a project.
Structure with easy to scan titles, headings, and subheadings.	Group content under abstract names.
Provide code snippets that demonstrate component use.	Create full demo applications.

Written by @CrystalOnScript