アドビドキュメントのコントリビューターガイドの概要

コラボレーティブドキュメントとは

2019 年、Adobe Experience Cloud のすべての技術ドキュメントおよびイネーブルメントコンテンツはすべて、GitHub、Markown、および Adobe Experience Cloud ソリューション(Adobe Experience Manager、Analytics、Launch、Target を含む)を活用し、オープンソースの原則に基づいて新しいプラットフォームへと移行中です。

このオープンソースモデルにより、コンテンツの品質、および顧客やドキュメントチーム、製品チーム間の通信が向上します。すべてのページで、コンテンツの有用性、問題のログ、および Git プルリクエスト(PR)としてコンテンツの提案事項をコントリビューションできるようになりました。アドビのドキュメントチームは、毎日のコントリビューションと問題を監視し、必要に応じて更新および調整をおこないます。

コラボレーティブドキュメントの操作

従業員、パートナー、顧客、または見込み客を含め、この資料の利用者は、このドキュメントにコントリビューションする方法を、いくつかのシンプルな方法から選択できます。

  • ページの有用性を評価する
  • 特定のページに対する問題のログ
  • アセットやコードのサンプルを使用し、クイック編集を送信して記事全体をオーサリングすることもできます

このガイドでは、操作や、この資料セットにコントリビューションする際に必要なすべての事柄について説明します。

既存ドキュメントのクイック編集

クイック編集は、ドキュメント内の小さな不備や欠落を修正するのに便利です。記事に以下のような編集ボタンが表示されている場合は、閲覧者がその場で修正できます。文書を編集するときには、修正または提案をアドビに提出するためのプルリクエスト(PR)を送信します。その提案をアドビがレビューして承認し、公開します。

  1. 同意できる場合はコントリビューター使用許諾契約(CLA)に署名します。

    アドビの CLA は 1 回提出すれば済みます。

  2. 右列の Edit this page アイコンをクリックして、GitHub の markdown ソースファイルに移動します。

    このページを編集アイコン

  3. 鉛筆アイコンをクリックして記事を編集します。

    メモ

    鉛筆アイコンがグレー表示になっている場合は、GitHub アカウントにログインするか、新しいアカウントを作成する必要があります。

    鉛筆アイコンの場所

  4. Web エディターで変更をおこないます。「Preview changes」タブをクリックすると、変更部分の書式を確認できます。

  5. 変更を済ませたら、ページの下部までスクロールします。PR のタイトルと説明を入力し、次の図に示す「Propose file change」をクリックします。

    変更の提案

    メモ

    コントリビューター使用許諾契約(CLA)への署名に関する検証エラーメッセージが表示されたら、「詳細」をクリックしてライセンス契約書を開きます。同意できる場合は、契約に署名します。次に、プルリクエストを閉じてから開いて続行します。

必要な操作は以上です。ご協力ありがとうございます。提出されたプルリクエストをドキュメントチームメンバーがレビューしてマージします。

問題のログ

コンテンツの一部についての問題を指摘するもう 1 つの方法は、その問題をログに記録することです。

  1. コンテンツの一部に問題がある場合は、右列にある「Log an Issue」アイコンをクリックします。

    メモ

    問題をログに記録するには、GitHub アカウントにログインするか、新しいアカウントを作成する必要があります。

    このリンクをクリックすると、GitHub Issue インターフェイスを使用して、アドビ宛のクイックチケットを登録できます。

  2. 問題を含むページの URL が説明フィールドに自動的に挿入されます。タイトルを入力し、問題の簡単な説明を書いてから、「Submit new issue」をクリックします。

問題を送信すると、このページを担当するコンテンツチームに直接通知が送られます。担当チームがコンテンツを更新すると、GitHub Issues インターフェイス上で登録者に通知されます。問題に進展があるか、問題がクローズされると、電子メールで通知されます。

GitHub の権限について

GitHub の編集 UI は、利用者のリポジトリ権限に応じて変化します。前掲の画像は、ターゲットリポジトリへの書き込み権限を持たないコントリビューターに表示されるものです。GitHub は自動的に利用者のアカウント内にターゲットリポジトリのフォークを作成します。利用者がターゲットリポジトリへの書き込み権限を持っている場合は、GitHub はターゲットリポジトリ内に新しいブランチを作成します。

アドビはすべての変更でプルリクエストを使用します。書き込み権限を持つコントリビューターによる変更でも同様です。ほとんどのリポジトリには保護されたmasterブランチがあり、アップデートはプルリクエストとして送信される必要があります。

ブラウザー内編集の機能は、小さな変更や頻繁でない変更に適しています。大きな変更を加える場合や、高度な Git 機能を使用する場合は、リポジトリをフォークしてローカルで作業することをお勧めします。

フィードバックの提供

アドビのソリューションセットのように大規模なものになると、ドキュメントは常に作業中になります。エラーを見つけた場合はログに記録し、提案がある場合はアドビまでお知らせください。どのような情報を探しているか、ご意見をお聞かせください。必要な情報が見つからない場合は、その旨をお知らせください。タスクをうまく完了できない場合は、どこがわからないかをご指摘ください。

コラボレーティブドキュメントの担当チームと Adobe Experience Cloud のすべてのライターおよびコンテンツプロデューサーを代表して、皆様のご協力に感謝を申し上げます。

このページ