AMP
JA
English Deutsch Français العربية Español Italiano Indonesia 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

ドキュメントの種類

以下は、amp.dev で貢献が許可されるドキュメントの種別に関する簡単なアウトラインです。

基礎チュートリアル

基礎チュートリアルは、開発者が技術の全容を理解することを目的としています。コーディングから始まり、最終的に「Hello World」プロジェクトの完成までを指導する構成です。基礎チュートリアルでは、AMP の主な機能を構築する方法を手順を追って説明しています。基礎チュートリアルには、開発者による最小限の調整で実行できるインラインコードサンプルやダウンロード可能なサンプルを組み合わせるようにしてください。

amp.dev の例:

やるべきこと やってはいけないこと
簡単な説明と最小限の手順でガイダンスを提供する。 プロジェクトのニュアンスを詳しく説明する。チュートリアルの結果を完成させるには多くの方法があるかもしれませんが、すべてのやり方ではなく、1 つの最適なやり方を示すことにポイントがあります。
セットアップの環境とツールを単純に維持する。 開発者が製品に精通しており、エキスパートレベルのコーディング能力を備えていると仮定する。
視覚的にシンプルなサンプルを維持する。 見栄えをよくしようとして複雑なものを提示する。スタイルに関するチュートリアルの場合は除きます。
各手順と完成したデモのスクリーンショットを提供する。 コードサンプルのみを提供する。
行動喚起を作成する。開発者が何を確認すべきか示してください。 例と追加説明を混在させる。説明が不十分と感じられる場合は、ガイドまたはチュートリアルに関する課題の作成を検討してください。

高度なチュートリアル

高度なチュートリアルでは、開発者は特定のタスクを完成させます。開発者がある程度 AMP を理解していることを前提とし、エクスペリエンスの構築、機能の統合、または実装タスクへの取り組みといった方法を示すものである必要があります。

amp.dev の例:

やるべきこと やってはいけないこと
最終プロジェクトを明確化し、手順をおって指示を示す。 徹底した詳細と綿密な概念を示す。
コードサンプルまたはダウンロード可能な基本コードを提供する。また、最終的な完成プロジェクトをダウンロードできるようにしてください。 最終結果を得るための代替例やプロセスを紹介する。
プラグアンドプレイ環境を作成する。 セットアップチュートリアルへのリンクを設定する。チュートリアル内ですべてを説明してください。

導入ガイド

導入ガイドは、AMP に着手するための関連情報の概要を提供するものです。機能を取り上げて、それが何であるのか、そして何を行うのかを説明してください。導入ガイドには、開発者に実装させずに基本要件を紹介する役割があります。コードサンプルを使って手順をおったプロセスを紹介している場合、それはチュートリアルの作成になる可能性があります。また、AMP コンポーネントのすべてのプログラミング要素を要点的に説明している場合、リファレンスドキュメントの作成である可能性があります。

amp.dev の例:

やるべきこと やってはいけないこと
ドキュメントで説明する内容を明確にする。 プロセスを手順を追って示す。
機能と概念を紹介する。高度な使用方法の詳細については、リファレンスドキュメントにリンクしてください。 詳細を徹底的に説明する。
コードサンプルと実世界の例を示す。 アプリ全体を作成する。さらに説明する代わりに、例やデモにリンクしてください。
技術的な使用や制約をリストする。 可能性のあるすべての技術的な使用やそのやり方をリストする。

概念ガイド

概念ガイドは、開発者が AMP をより深く理解するためのドキュメントです。地形図のようなもので、標高の変化といった詳細ともに、エリア内のさまざまな道を示しますが、地上の特定の道のりを示すことはありません。概念ガイドでは、機能の構築方法ではなく、機能が何であるか、そしてどのように機能するのかを説明してください。

amp.dev の例:

やるべきこと やってはいけないこと
ソリューションを構築するために必要なすべての要素を開発者に示す。 特定の最終状態に開発者を積極的に誘導する。
主題エリアのすべての側面を説明する。 特定のタスクに焦点を当てる。
図やスクリーンショットなど、視覚的な資料を含める。 これに悩んでしまう場合は、[outreach ワーキンググループ]（https://github.com/ampproject/wg-outreach）に視覚資料に関する支援をリクエストできます。
コードサンプルとほかのガイドへのリンクを示す。 完成したプロジェクトやオフトピックへのダウンロードを提供する。

リファレンスドキュメント

リファレンスドキュメントには、AMP コンポーネントのすべてのプログラミング要素がリストされます。動作に関する詳しい情報を示し、精査できるようにデザインされるものです。リファレンスドキュメントには例示的なコードサンプルを含め、使用事例を実演する必要があります。

amp.dev リファレンスドキュメントは、AMP コンポーネントカタログの配下にあります。

AMP リファレンスドキュメントは、AMPHTML リポジトリ に寄与されています。

やるべきこと やってはいけないこと
コンポーネントがどのように振る舞うかについて、明確かつ明瞭な言葉で説明する。 プロジェクトのプロセスや構築を説明する。
題名、見出し、小見出しを精査しやすく構成する。 抽象的な題名や見出しの下にコンテンツをグループ化する。
コンポーネントの使用方法を実演するコードスニペットを提供する。 完全なデモアプリケーションを作成する。