このページでは、Experience League でコンテンツを作成したり、既存のコンテンツを更新したりする外部の作成者向けのエディトリアルガイドラインを示します。開始する前に、次の事項を確認します。
ドキュメントを記述する際は、次の点に留意してください。
テクニカルライティング、特にソフトウェアドキュメントの執筆は専門的な業界です。最も多作な小説家でさえ、テクニカルライティングを試みると慌ててしまいます。それは、資料が複雑または技術的だからではなく、複雑な技術情報を単純にするのが簡単ではないからです。成功するには、コンテンツが構造的に一貫し、スキャンや再利用が可能で、構造や構文エラーが発生することなくパブリッシングパイプラインを進む必要があります。
以下の節では、新人ライターにとって注意が必要な、一般的な問題について説明します。
2 つの見出しがあり、それらを区切るテキストがない場合は、不足しているテキストを追加します(2 番目のトピックの見出しを導入するため)。または、いずれかの見出しを削除できます。2 番目はおそらく必要ありません。
たとえば、概要はここでは意味がありません。
また、2 番目の見出しがたまたま概要である場合、おそらくこの見出しは必要ありません。H1 と最初の段落は、記事のトピックに関する概念的な概要として機能します。
同様に、SEO の目的では、概要や紹介などのスタンドアロンの見出しは、単体では役に立ちません。紹介する製品または機能に名前を付けます。(例:フォールアウトレポートの概要)
相互参照リスト(またはマップ)には、詳細情報の見出しを使用します。例:
相互参照リストのガイダンス
TOC(目次)ファイルを手動で管理しているので、これらの不一致は簡単な間違いです。TOC エントリがページ名(H1)と一致することを確認します。また、パンくずリストと密接に一致することを確認します。
TOC とリストに関するガイダンス
単語やフレーズの前後に引用符を追加するのは避けられません。ただし、引用符は発言を引用することを目的としており、製品ドキュメントで使用されることはほとんどありません。
引用符に関するガイダンス
プロシージャ(タスクコンテンツタイプ)を書く能力は、生まれつきの才能ではありません。読みやすく明確なプロシージャを作成するには、練習が必要です。
手順のガイダンス
プロシージャの例
以下に示すのは、アドビにログインするための、適切に構成された手順です。
アドビにログインするには:
Adobe.com
で「Experience Cloud」を選択します。リストに並列構造を使用すると、読み取りとスキャンが簡単になります。リストには、TOC(目次)、箇条書き(順不同)リスト、番号付きリストが含まれます。
並列エントリを含む目次の例:
上記の目次は、次の理由から良い例となります。
タイトルと説明のメタデータは、Experience League の SEO、コンテンツ検出およびコンテンツ品質スコアにとって重要です。
以下に示すのは、タイトルと説明の例です。
概念に関する記事の説明
プロシージャ/タスクに関する記事の説明
どちらを使用するかは、記事のサイズと範囲によります。
概念に関する記事のタイトル
プロシージャ/タスクに関する記事のタイトル
なお、パイプと製品名はタイトルに自動的に追加されます。
コンテンツのデザイン、明確さおよび読みやすさを向上させる簡単な方法を次に示します。これらは ExL で Acrolinx スタイルスコアと CQI スコアを改善する際にも役立ちます。
ガイダンス | 概要 |
---|---|
能動態を使用する | 受動態を能動態に変更する |
現在形を使用する | 弱: Campaign v8 は 6月にリリースされる予定です。 強: Campaign v8 は 6月にリリースされます。 現在時制は、顧客にとって常に読みやすいものです。 |
説得力のない不必要な副詞を避ける | 非常に、極めて、信じられないほど… 説得力のある正確な動詞、句および形容詞を使用する場合、副詞は、重要な意味を追加しない余分な単語です。 |
タイトルおよび目次エントリには明確な動詞を使用する | 例: 弱: 特性の作成と管理 強: 特性を作成および管理する |
文の先頭を大文字にする | 不確かな場合は、大文字にしないでください。見出しでは、文と同様に先頭を大文字にします。固有名詞とコロンの後の最初の単語は先頭を大文字にします。プロシージャでは、インターフェイスでの表示と同じように大文字を使用します。 |
明確にするためのちょっとしたヒント |
|
VSC でのスペルチェッカーの使用 | Visual Studio Code にコードスペルチェック(拡張機能)をインストールします。 |
「クリック」を「移動」または「選択」に変更する | 「クリック」はデバイス固有の単語(アクセシビリティの問題を含む)であり、使用頻度は減る傾向にあります。 次のように変更することを提案します。
|
VSC での Acrolinx の実行 | Acrolinx はスタイルと文法の問題をチェックします。 URL、用語、スペルなどをチェックします。 これにより、 Experience League コンテンツの明確さが向上し、翻訳の質が向上します。 |
その他のベストプラクティスとリソース:
詳しくは、Microsoft® スタイルガイドの Top 10 Writing Tips(ライティングのヒントトップ 10)を参照してください。
アセット(画像)に意味のある代替テキストを追加します。次の条件に一致する代替テキストを検討します。
Google は、SEO の結果で代替テキストを検討します。
製品がローカライズされているかどうか、または ExL が使用する言語について心配する必要はありません。ただし、必要に応じて次の 2 つの Markdown タグ(必須)を適用することで、ローカライゼーションの品質を向上させることができます。
DNL
DNL は、do not localize(ローカライズしない)を意味します。商標登録されたアドビ製品名にのみ使用します。これらはすべて英語のままにする必要があります。
構文の例:Adobe Campaign
または Workfront
DNL は、ファイル名や URL には使用しません。
UICONTROL
UICONTROL は、インターフェイスコントロール(オプション、フィールド、タブ、ページ、オプションのグループ、UI の機能名など)を示します。
構文の例:Select **Project**, then select **Save**.
コンテンツをローカライズする前に、これらのタグを適用する必要があります。
企業アイデンティティのため、アドビでは通常、ガイドレベルで製品を最初に参照する際に Adobe を含めます。スペースの都合に応じて、見出しでは「Adobe」を省略することもできますが、本文コピーの最初の参照には完全な名前を含める必要があります。 Adobe Audition や Adobe Premiere Pro など、特定の製品では法的な商標名の一部となっているため、すべての資料の最初または最も目立つ参照で Adobe を使用する必要があります。
最初の段落では、トピックを定義し、読み手が記事を読んで学ぶ内容について説明する必要があります。
最初の段落の例(概念):
オーディエンスは、訪問者の集まり(訪問者 ID のリスト)です。アドビのオーディエンスサービスは、訪問者データからオーディエンスのセグメント化への変換を管理します。したがって、オーディエンスの作成や管理は、セグメントの作成や管理と似ていますが、オーディエンスセグメントを Experience Cloud と共有する機能が追加されています。
最初の段落の例(タスク):
顧客属性ソース(CSV および FIN ファイル)を作成してデータをアップロードします。準備できたら、データソースをアクティブ化できます。データソースがアクティブになったら、属性データを Analytics と Target で共有します。
TOC.md
は目次です。ガイドごとに 1 つずつ必要です。
目次のエディトリアルガイダンス
構文ガイダンス
{#processing-rules}
などのアンカーを含める必要があります。+ Processing rules {#processing-rules}
)および目次の記事リンク(例:+ [Article name](article.md)
)には適切な構文を使用する必要があります。help
ディレクトリ内のサブディレクトリなど、同じレベルにある必要があります。各ユーザーガイドディレクトリには、目次ファイルが必要です。ユーザーガイドにネストは使用しないでください。