オーサリングのベストプラクティス

最終更新日： 2023-11-01

概要

このページでは、Adobe Experience Platform ドキュメント品質基準を確実に満たすために、宛先ドキュメントページをオーサリングする際に従うべきルールについて説明します。

宛先ドキュメント用にテンプレートに入力する場合、リンク、テーブル、サポートされるマークダウン構文、ライティングガイダンスなどについて詳しくは、アドビコントリビューターガイドを参照してください。
製品ドキュメントに所見や推定を含めないでください。
Experience Platform ドキュメントでは、アドビのライターは、ユーザーインターフェイスコントロールを参照するために、以下のように、太字書式を使用しています。
- 接続／宛先に移動し、「カタログ」タブを選択します。ユーザーインターフェイスコントロールの表記方法の例を表示するには、宛先チュートリアルを参照してください。

重要

宛先ドキュメントページのオーサリングを開始する前に、アドビドキュメントのライティングガイダンスを参照してください。

文を短くして、要点を早く伝えます。文が 20 単語を超える長さだったり、複数のコンマを使用している場合は、別の文に分割することを検討してください。20 単語を超える長さの文は、読者にとって特に読みにくい可能性があります。
過剰に丁寧な表現をしないようにします。テクニカルドキュメントでは、「お願いいたします」や「…していただく」などの使用は避けます。

提供されるドキュメントテンプレートに従い、テンプレート内の既存のリンクを編集しないようにします。新しいリンクを含める場合は、コントリビューターガイドのドキュメントでのリンクの使用を参照してください。

AEP は、承認された、一般向けの用語ではありません。最初の使用時には Adobe Experience Platform を使用し、次に Experience Platform、その次に Platform を使用してください。
- 使用不可：AEP から宛先にデータを書き出す前に、以下の前提条件を参照し、必ず完了するようにしてください。
- 使用可：Adobe Experience Platform から宛先にデータを書き出す前に、以下の前提条件を参照し、必ず完了するようにしてください。

画像へのリンク方法について詳しくは、コントリビューターガイドを参照してください。
スクリーンショットを使用する場合、スクリーンショットが Platform UI 画面全体をキャプチャしていることを確認してください。
ページ上の特定のコントロールやラベルをハイライト表示するために画像をマークアップする場合、Experience Platform ドキュメントチームによって使用されるマークアップスタイルに従ってください。このスクリーンショットで「Profile-based」がどのようにハイライト表示されているかを確認してください。
png 形式の画像を使用してください。
番号が付けられたスクリーンショットをファイル名として使用しないでください。画像ファイル名は、説明的である必要があります。
- 使用不可：1.png、2.png、3.png
- 使用可：yourdestination-authentication-details.png、yourdestination-destination-details.png
ドキュメントに追加するすべての画像に alt テキストを使用し、alt テキストに適した文法を使用してください。
- 使用不可：宛先接続の詳細
- 使用可：宛先接続の詳細が入力されていることを表す、Platform UI の画像。

ドキュメントテンプレートは、パートナーのフィードバックに基づいて、まれに更新されます。宛先用のドキュメントのオーサリングを開始する前に、テンプレートの最新バージョンをダウンロードしていることを確認してください。
ドキュメントをオーサリングして、メインブランチ以外のフォーク内のブランチからドキュメントのプルリクエスト（PR）を作成します。GitHub インターフェイスやローカル環境でオーサリングする場合は、レビューのための宛先の送信に関する節を参照してください。