外部寄稿者向けのオーサリングスタイルガイドライン

このページでは、Experience League でコンテンツを作成したり、既存のコンテンツを更新したりする外部の作成者向けのエディトリアルガイドラインを示します。開始する前に、次の事項を確認します。

  • Markdown オーサリングに精通する
  • 誤字脱字や文法的な間違いがないようにする
  • わかりやすいトーン、一貫性のあるプレゼンテーション、シンプルな文を使用して、機械翻訳を改善する
  • このページのベストプラクティスと編集基準に従う

スタイルのガイドライン

ドキュメントを記述する際は、次の点に留意してください。

  • 簡潔に書く：冗長な表現を避けます。文は短く簡潔にします。記事の焦点を絞ります。メモの数は最小限にします。
  • 対象と目的を絞る：書き始める前に、読み手は誰で、何のタスクを実行しようとしているかを明確にします。読み手がそのタスクを実行するときに役立つような記事を書きます。
  • 例を示す：概念を説明する例を示します。
  • コンテンツを整理する：いくつかのセクションを設け、手順をいくつかの扱いやすいグループに分けるようにします。画面を示した方がわかりやすいときは、スクリーンショットを追加します。

テクニカルライティングのベストプラクティス

テクニカルライティング、特にソフトウェアドキュメントの執筆は専門的な業界です。最も多作な小説家でさえ、テクニカルライティングを試みると慌ててしまいます。それは、資料が複雑または技術的だからではなく、複雑な技術情報を単純にするのが​簡単​ではないからです。成功するには、コンテンツが構造的に一貫し、スキャンや再利用が可能で、構造や構文エラーが発生することなくパブリッシングパイプラインを進む必要があります。

以下の節では、新人ライターにとって注意が必要な、一般的な問題について説明します。

見出しがテキストで区切られていない（二重見出し）

2 つの見出しがあり、それらを区切るテキストがない場合は、不足しているテキストを追加します（2 番目のトピックの見出しを導入するため）。または、いずれかの見出しを削除できます。2 番目はおそらく必要ありません。

たとえば、概要​はここでは意味がありません。

二重見出し

  • また、2 番目の見出しがたまたま​概要​である場合、おそらくこの見出しは必要ありません。H1 と最初の段落は、記事のトピックに関する概念的な概要として機能します。

  • 同様に、SEO の目的では、概要​や​紹介​などのスタンドアロンの見出しは、単体では役に立ちません。紹介する製品または機能に名前を付けます。（例：フォールアウトレポートの概要）

相互参照の見出しに一貫性がない

相互参照リスト（またはマップ）には、詳細情報​の見出しを使用します。例：

相互参照リスト

相互参照リストのガイダンス

  • 相互参照に箇条書きリストを使用する
  • ガイドの正式名またはページ名には斜体を使用する（リンクテキストを使用しない場合）
  • 見出し（または任意の見出し）に句読点を付けない
  • 見出しに数字を使用しない

TOC エントリ、パンくずリストおよびページ名が一致しない

TOC（目次）ファイルを手動で管理しているので、これらの不一致は簡単な間違いです。TOC エントリがページ名（H1）と一致することを確認します。また、パンくずリストと密接に一致することを確認します。

TOC とリストに関するガイダンス

  • TOC エントリを短くする必要があるかもしれませんが、ページ名とパンくずリストに明確に関連している必要があります。
  • パンくずリストはタイトルメタデータから取り込まれるため、（SEO 目的で）異なる場合があります。

斜体の代わりの引用符

単語やフレーズの前後に引用符を追加するのは避けられません。ただし、引用符は発言を引用することを目的としており、製品ドキュメントで使用されることはほとんどありません。

引用符に関するガイダンス

  • 通常は、引用符よりも斜体の方が効果的です（エラーメッセージ、独特の語句、外国語などの場合）。
  • インターフェイス要素には、太字と UICONTROL を使用します。

プロシージャ

プロシージャ（タスク​コンテンツタイプ）を書く能力は、生まれつきの才能ではありません。読みやすく明確なプロシージャを作成するには、練習が必要です。

手順のガイダンス

  • プロシージャは一連の手順です。手順とは、番号付けされた簡潔な​単文​のコマンドのことです。
  • 各手順は、動詞または To 不定詞で開始して、読み手を目標に誘導します（例：「ログインしたままにするには、「ログインしたままにする」を有効にします」）。手順全体で特定の目標が設定されている場合は、アクションの前にその目標に言及します。
  • 手順に関する情報（手順情報​と呼ばれるコンテンツタイプ）がある場合は、手順の後（手順でインデント）またはアセット（スクリーンショット、ビデオまたはインターフェイスの説明のリスト）の後に追加します。
  • 手順に 2 つのアクション（これを選択して、次にそれを選択​など）がある場合は、1 つの簡潔な文として記述します。
  • タスクを 7～10 手順程度に制限します。1 つのタスクで 10 を超える手順を作成する場合は、2 つのタスクに分割した方がよいでしょう。ここで最善の判断をします。
  • 製品ドキュメントでは、見出しを手順として使用しません（以下のチュートリアルは例外です）。
  • 複数ページのチュートリアルの場合、見出しを手順として使用できます。ただし、番号は付けません。代わりに、手順 1：、手順 2：​などを記載します。

プロシージャの例

以下に示すのは、アドビにログインするための、適切に構成された手順です。

アドビにログインするには：

  1. Adobe.com で「Experience Cloud」を選択します。
  2. 「ログイン」を選択します。
  3. 「個人アカウント」を選択します。
  4. ログインしたままにするには、「ログインしたままにする」を選択します。
  5. 名前とパスワードを入力します。
  6. 「ログイン」を選択します。

並列リスト

リストに並列構造を使用すると、読み取りとスキャンが簡単になります。リストには、TOC（目次）、箇条書き（順不同）リスト、番号付きリストが含まれます。

並列エントリを含む目次の例：

並列目次

上記の目次は、次の理由から良い例となります。

  • 概念的な親エントリは、名詞または名詞句です
  • プロシージャ（タスク）は動作動詞です（動名詞ではありません）
  • すべてのエントリで文の先頭を大文字にします

タイトルと説明のメタデータ

タイトル​と​説明​のメタデータは、Experience League の SEO、コンテンツ検出およびコンテンツ品質スコアにとって重要です。

以下に示すのは、タイトルと説明の例です。

概念に関する記事の説明

  • Adobe Analytics のセグメントについて説明します。 ワークスペースでのセグメント化パネルの設定に関するヘルプを示します。
  • Adobe Analytics のページビュー数レポートでのセグメントの使用に関するヘルプを示します。

プロシージャ／タスクに関する記事の説明

  • Adobe Analytics でセグメントを作成する方法について説明します。
  • Adobe Analytics でセグメントを作成します。作成したセグメントに基づいてレポートを選択、設定および実行する方法について説明します。

どちらを使用するかは、記事のサイズと範囲によります。

概念に関する記事のタイトル

  • ページビュー数レポートのセグメント

プロシージャ／タスクに関する記事のタイトル

  • ページビュー数レポート用のセグメントの作成

なお、パイプと製品名はタイトルに自動的に追加されます。

明確さを向上させる方法（および Acrolinx スコア）

コンテンツのデザイン、明確さおよび読みやすさを向上させる簡単な方法を次に示します。これらは ExL で Acrolinx スタイルスコアと CQI スコアを改善する際にも役立ちます。

ガイダンス 概要
能動態を使用する 受動態を能動態に変更する
現在形を使用する 弱： Campaign v8 は 6月にリリースされる予定です。

強： Campaign v8 は 6月にリリースされます。

現在時制は、顧客にとって常に読みやすいものです。
説得力のない不必要な副詞を避ける 非常に、極めて、信じられないほど…

説得力のある正確な動詞、句および形容詞を使用する場合、副詞は、重要な意味を追加しない余分な単語です。
タイトルおよび目次エントリには明確な動詞を使用する 例：

弱： 特性の作成と管理

強： 特性を作成および管理する
文の先頭を大文字にする 不確かな場合は、大文字にしないでください。見出しでは、文と同様に先頭を大文字にします。固有名詞とコロンの後の最初の単語は先頭を大文字にします。プロシージャでは、インターフェイスでの表示と同じように大文字を使用します。
明確にするためのちょっとしたヒント
  • In order to（～をするためには）​という表現は避けてください（意味を追加するものではないからです）。 to（～するには）​という表現で十分です。
  • Utilize（活用する） より専門的な表現に聞こえるかもしれませんが、実際はそうではありません。 Utilize（活用する）​という単語には、うまく利用する、特に意図していなかったものを代わりに利用する​という意味があります。
  • セミコロン（；）を避ける：代わりにピリオドを使用し、新しい文章を始めます。 セミコロンは不必要に複雑化させてしまいます。
  • コロン（：）：リストの表示にはコロンを使用します。 文の中ではコロンの使用は控えめにします。 文のコロンの後の最初の単語を大文字にします。
  • Oxford コンマ（リスト内の 3 つのコンマ）を使用します。
  • 文の長さは 39 語以内に抑えます。
  • ナビゲーション：移動​または​ナビゲート​を使用します。
  • パスの表示が重要な情報でない限り、生の URL テキストは避けます（ユーザーにわかりやすいリンクテキストを使用します）。
VSC でのスペルチェッカーの使用 Visual Studio Code にコードスペルチェック（拡張機能）をインストールします。
「クリック」を「移動」または「選択」に変更する 「クリック」はデバイス固有の単語（アクセシビリティの問題を含む）であり、使用頻度は減る傾向にあります。 次のように変更することを提案します。
  • ナビゲーション：ファイル／印刷に移動します。
  • クリック： ファイル／印刷を選択​または OK を選択​します。
様々な状況での最良の単語選択に関するより多くのアイデアについては、UI とのインタラクションの説明を参照してください。
VSC での Acrolinx の実行 Acrolinx はスタイルと文法の問題をチェックします。 URL、用語、スペルなどをチェックします。 これにより、 Experience League コンテンツの明確さが向上し、翻訳の質が向上します。

その他のベストプラクティスとリソース：

  • スキャン可能なコンテンツ：読み手が必要なものを素早く見つけたり、必要な場所にない場合はすぐに認識したりできます。 スキャンを容易にする内容を記述すると役に立ちます。
  • 数値：​本文では、0 から 9 までの整数を入力し、10 以上の数字を使用します。 数値を参照してください。
  • 話し言葉で書いて親しみやすさを示し、すばやく要点を示します。

詳しくは、Microsoft® スタイルガイドの Top 10 Writing Tips（ライティングのヒントトップ 10）を参照してください。

代替テキスト

アセット（画像）に意味のある代替テキストを追加します。次の条件に一致する代替テキストを検討します。

  • 顧客が達成できる目標（タスク名またはコンセプト名）
  • 表示している機能またはページ
  • 表示しているアイコン名

Google は、SEO の結果で代替テキストを検討します。

ローカライゼーション - DNL および UICONTROL

製品がローカライズされているかどうか、または ExL が使用する言語について心配する必要はありません。ただし、必要に応じて次の 2 つの Markdown タグ（必須）を適用することで、ローカライゼーションの品質を向上させることができます。

  • DNL

    DNL は、do not localize（ローカライズしない）を意味します。商標登録されたアドビ製品名にのみ使用します。これらはすべて英語のままにする必要があります。

    構文の例：Adobe Campaign または Workfront

    DNL は、ファイル名や URL には使用しません。

  • UICONTROL

    UICONTROL は、インターフェイスコントロール（オプション、フィールド、タブ、ページ、オプションのグループ、UI の機能名など）を示します。

    構文の例：Select **Project**, then select **Save**.

重要

コンテンツをローカライズする前に、これらのタグを適用する必要があります。

製品名での Adobe の使用

企業アイデンティティのため、アドビでは通常、ガイドレベルで製品を最初に参照する際に Adobe を含めます。スペースの都合に応じて、見出しでは「Adobe」を省略することもできますが、本文コピーの最初の参照には完全な名前を含める必要があります。 Adobe Audition や Adobe Premiere Pro など、特定の製品では法的な商標名の一部となっているため、すべての資料の最初または最も目立つ参照で Adobe を使用する必要があります。

最初の段落

最初の段落では、トピックを定義し、読み手が記事を読んで学ぶ内容について説明する必要があります。

最初の段落の例（概念）：

オーディエンスは、訪問者の集まり（訪問者 ID のリスト）です。アドビのオーディエンスサービスは、訪問者データからオーディエンスのセグメント化への変換を管理します。したがって、オーディエンスの作成や管理は、セグメントの作成や管理と似ていますが、オーディエンスセグメントを Experience Cloud と共有する機能が追加されています。

最初の段落の例（タスク）：

顧客属性ソース（CSV および FIN ファイル）を作成してデータをアップロードします。準備できたら、データソースをアクティブ化できます。データソースがアクティブになったら、属性データを Analytics と Target で共有します。

最初の段落に関する SEO のヒント

  • 最初の段落に検索用語を含めます。
  • 読み手が使用する用語を使用します。
  • 同義語と、必要に応じて用語の以前の用法を含めます。例えば、「以前は​訪問者 ID または MID、MCVID などの頭字語として知られていた Experience Cloud ID サービス（ECID）は、訪問者を識別する普遍的で永続的な ID を提供します。」
  • リンクに SEO 用語を含めます。
  • 複雑なテーブルに重要な用語を入れないようにします。複雑なテーブルでは、信頼できる検索結果が得られません。画像内のテキストは検索対象外です。キャプションが検索されます。

大文字／小文字

  • アドビのスタイルでは、すべてのタイトル、見出し、サブ見出しおよびページナビゲーション要素に文スタイルの大文字／小文字を使用します。
  • ブランド、ソリューション、サービスの名前など、最初の単語と固有名詞を除くすべての単語は小文字です。
  • ツール、オプション、メニュー項目、ダイアログボックスおよびフィールドの製品名の大文字と小文字を一致させます。

目次

TOC.md は目次です。ガイドごとに 1 つずつ必要です。

目次のエディトリアルガイダンス

  • 大文字／小文字：すべてのエントリで常に文頭のみ大文字を使用します（頭字語は含みません）。正式な製品名またはインターフェイス要素（ページ、タブ、フィールド、オプションなど）のみを大文字にします。参照元の UI と一致させます。
  • 動詞の形と並列性：命令形の動詞を使用し、動名詞を避けます。目次はリストです。そのため、ほとんどの場合、常にリストを並列に保つようにします。場合によっては、例外となるのを避けられないことがあります。概念的なページには、名詞と名詞句を使用します。タスクには、動詞を使用します。

構文ガイダンス

  • 目次のセクション見出し（親）をリンクにすることはできません。コンテンツを含むページがありません。{#processing-rules} などのアンカーを含める必要があります。
  • 目次のセクション見出し（例：+ Processing rules {#processing-rules}）および目次の記事リンク（例：+ [Article name](article.md)）には適切な構文を使用する必要があります。
  • 目次の記事エントリは、記事のタイトルの短縮バージョンにすることができます。このドキュメントの概要、概念およびタスクを記述する基準に従います。
  • 同じファイルを 1 つの目次（または複数の目次）に複数回追加することは避けます。動作がおかしくなる原因となります。
  • リポジトリに複数のユーザーガイドが含まれている場合、ユーザーガイドディレクトリは、help ディレクトリ内のサブディレクトリなど、同じレベルにある必要があります。各ユーザーガイドディレクトリには、目次ファイルが必要です。ユーザーガイドにネストは使用しないでください。

太字と斜体

  • 手順内で（および UICONTROL で）クリックするインターフェイス要素にのみ、太字のテキストを使用します。
  • 強調する場合や、そうしないとわかりにくい場合は斜体を使用します。例えば、外来語や、単語を説明したり、用語を定義したりする場合があります。

このページ