Содержание

Типы документации

Ниже приведен краткий обзор типов документации, принимаемой на amp.dev:

Вводный урок

Вводные уроки помогают разработчику понять общую идею технологии. Они начинаются с азов программирования и заканчиваются созданием полноценного проекта для начинающих. В таких уроках процесс создания ключевой функции AMP демонстрируется шаг за шагом. Вводные уроки следует дополнять примерами кода и/или скачиваемым образцом, для запуска которого требуется минимум корректировок.

Примеры с amp.dev:

Правильно	Неправильно
Предоставлять краткие инструкции, содержащие только необходимые действия.	Углубляться в нюансы проекта. Цель состоит не в том, чтобы описать все возможные способы завершить урок, а в том, чтобы показать один хороший способ.
Предоставлять упрощенную среду и инструменты для предварительной настройки.	Предполагать, что разработчик знаком с продуктом и обладает навыками программирования на уровне эксперта.
Следить за тем, чтобы примеры были наглядными и простыми.	Усложнять материал в угоду стилю, если только урок не посвящен стилю.
Предоставлять скриншоты каждого шага, а также завершенную демонстрацию.	Предоставлять только образцы кода.
Создать призыв к действию. Рекомендовать разработчику, что делать дальше.	Дополнять пример дальнейшими пояснениями. Если вам кажется, что тема нуждается в дополнительном раскрытии, можно создать запрос на создание руководства или урока.

Продвинутый урок

Продвинутые уроки помогают разработчикам выполнить конкретную задачу, предполагая, что разработчик знаком с AMP. Такой учебник должен продемонстрировать, как создать взаимодействие с пользователем, интегрировать функцию или решить задачи по реализации.

Примеры с amp.dev:

Правильно	Неправильно
Предоставлять пошаговые инструкции и понятный завершенный проект.	Предоставлять исчерпывающие подробности и в мельчайших деталях описывать сложные концепции.
Предоставлять примеры кода или скачиваемый стартовый код. Дать возможность скачать завершенный проект.	Предоставлять альтернативные примеры или альтернативный процесс достижения конечного результата.
Создавать окружение, функционирующее по принципу «plug and play».	Ссылаться на дополнительный урок по настройке. Уроки должны быть самодостаточными.

Вводное руководство

Вводное руководство предоставляет обзор информации, необходимой для начала работы с AMP. Такое руководство должно представить функцию, описать, что она из себя представляет, после чего объяснить, что она делает. Вводные руководства информируют разработчика о базовых требованиях функции, не являясь инструкциями по ее реализации. Если вы описываете пошаговый процесс с применением образцов кода, то, скорее всего, вы пишете урок. Если вы описываете все программные элементы AMP-компонента, вероятно, вы пишете справочный документ.

Примеры с amp.dev:

Правильно	Неправильно
Описывать, какие сведения охватывает документ.	Представлять документ в виде пошагового процесса.
Обозначать возможности и концепции. Давать ссылки на справочные документы с подробной информацией.	Описывать все в мельчайших подробностях.
Размещать образцы кода и реальные примеры.	Создавать завершенное приложение. Для дальнейшего рассмотрения вопроса следует размещать ссылки на примеры и демонстрации.
Перечислять технические применения и ограничения.	Перечислять и разбирать все возможные технические применения.

Концептуальное руководство

Концептуальные руководства помогают разработчикам получить углубленное понимание AMP. Концептуальное руководство похоже на топографическую карту — в нем представлены различные маршруты с сопутствующими подробностями, такими как рельеф местности, но не предписывается какой-либо определенный маршрут. Соответственно, в таком руководстве следует объяснять, для чего предназначена функция и как она работает, а не описывать, как ее создать.

Примеры с amp.dev:

Правильно	Неправильно
Предоставлять разработчику все элементы, необходимые для создания решения.	Активно направлять разработчика к определенной цели.
Затрагивать все аспекты предметных областей.	Концентрироваться на конкретной задаче.
Визуализировать информацию, например с помощью диаграмм и скриншотов.	Уделять визуализации слишком много внимания; за помощью в подборе визуальных материалов можно обратиться в [общественную группу поддержки](https://github.com/ampproject/wg-outreach).
Предоставлять образцы кода и ссылки на другие руководства.	Предоставлять ссылку на скачивание готового проекта, отклоняться от темы.

Справочная документация

В справочной документации перечисляются все программные элементы AMP-компонента и предоставляется подробная информация об их поведении. Такая документация предназначена для быстрого нахождения информации. Справочная документация должна содержать примеры кода и демонстрировать сценарии использования.

Справочные документы amp.dev находятся в каталоге AMP-компонентов.

Справочная документация AMP добавляется в репозиторий AMPHTML.

Правильно	Неправильно
Объяснять, как работает компонент, используя понятный и лаконичный язык.	Объяснять процесс или заниматься сборкой проекта.
Использовать удобную для чтения структуру с заголовками и подзаголовками.	Группировать содержимое, используя абстрактные наименования.
Предоставлять фрагменты кода, демонстрирующие использование компонента.	Создавать полноценные демонстрационные приложения.

Written by @CrystalOnScript