ソフトウェア リリースの文書化は、ソフトウェア開発チームの仕事の不可欠な要素であり、リリースの公開そのものと同じぐらい重要です。これには、次のような理由があります。 

• 可視性の増加 - リリースを文書化することで、チームの作業内容や、プロジェクトのマイルストーンに対する進行状況を確認できるようになります。 
• 継続的改善 - アジャイル チームは、各リリースを改善しようと努めています。リリース レポートを定期的に作成することで、チームは、完了した作業と、それらをどのように改善できるかを確認できます。
• 履歴の参照 - 過去の特定のリリースで完了した内容を、いつでも確認できます。 
• コミュニケーションの向上 - リリースの内容をサポート チームや運用チームに明確に報告し、詳細を含む課題リンクを提供します。

文書化の作業は、チームによっては好意的に受け入れられない場合があります。ただし、ここで案内する内容では、面倒な雑務や大幅な時間の浪費はありません。

ほとんどの作業の追跡やレポートに Jira を使用している場合、Confluence と Jira を統合することで、Jira から Confluence ページへ簡単にリリース結果を挿入できます。ここで、色や詳細の追加、社内での公開、または外部への公開を行うこともできます。

内部用リリース レポートを作成する

Start with the JIRA Reports Blueprint in Confluence. Select Create from template from the top nav (3-dot button next to ) > JIRA report > Change log  Create          

変更ログ レポートを選択し、内部用リリース レポートを作成します。このレポート タイプは、指定されたリリースまたはプロジェクトで完了された Jira 課題の詳細な概要を提供します。Confluence のレポートの作成ガイドを利用して、報告するリリースと、レポートに含める内容を指定できます。

適切なプロジェクトを選択します (複数の Jira インスタンスがある場合は、使用するサイトも選択します)。変更ログの作成画面で適切なフィールドに入力し、作成を選択します。変更ログ レポートには、Jira から指定したデータや、編集および調整できるその他の重要なページ要素が含まれます。 

課題の動的または静的なリストを作成できます。リリース ノートはある時点でのコミュニケーションに使用されるため、静的なリストが最適です。動的なリストを含める場合は、詳細設定に切り替えリンクをクリックして、カスタム JQL を入力します (詳細は、Jira レポート ブループリントのドキュメントを参照してください)。

編集モードではページは次のようになります。

ページの上部:

保存後:

ご覧のように、この変更ログはバグ修正に焦点を当てています。

Confluence は Jira での課題タイプに基づいて、リリースを自動的に「バグ修正」、「新機能」、「改善」などに分類します。この自動化は非常に便利で、手動で編集や書式設定を行う手間が大幅に削減されます。

公開用リリース ノートを作成する  

独自のリリース ノート テンプレートを作成して、何度も使用できる、カスタマー用の完全なリリース ノートを作成します。弊社が Jira リリース ノートをドキュメント サイトで公開する際に使用するテンプレートの例を次に示します。

テンプレートには、ページ作成者のガイドに役立つ説明テキストを含めました。一番上には、リリースの内容または主なテーマをまとめた短いテキストを含めることが重要です。ただのバグ修正の場合、このスペースに追加することはほとんどありません。ただし、メジャー リリースの場合、新機能の影響などに関するテキストを追加することを検討してください。

ページに含まれる内容:

マクロ:

• • 目次マクロ - リリース ノートのすべてのコンテンツの短い概要を提供します。
  • Jira 課題マクロ – リリースで解決したすべての課題、および投票数が多い人気の課題の詳細を表示します。
      

ページの拡張:

• • スクリーンショットとビデオ - メジャー リリースの場合、新しい機能と改善点を紹介するスクリーンショットやデモ ビデオを追加できます。

• • 権限と制限 - 権限は、リリース ノートでは重要です。下書きの間はリリース ノートを非公開にし、全体をレビューすることをおすすめします (Confluence のインライン コメントは、ドキュメントのレビューに非常に便利です)。公開する準備が整ったら、表示権限を調整します (詳細については、「技術文書の公開に Confluence を使用する」のガイドをお読みください)。

リリース ノート テンプレートの編集と整理

任意のページ テンプレートにさらに詳細を追加できます。内部および公開リリース ノートで「バグ修正」や「新機能と改善」のセクションを使用して、公開済みまたは修正済みの内容をを整理できます。マクロ (イメージ、スクリーンショット、およびビデオ) を追加することもできます。 

2 つの点に留意する必要があります。

1. リリース ノートは、組織内のユーザーにも、組織外のユーザーにも重要です。
2. Confluence でリリース ノート テンプレートを設定することで、最小限の労力で両方のオーディエンスに情報を伝えることができます。

リリース ノートのコンテンツに関する 6 つの考慮事項

1. 対象者: リリース ノートは誰を対象としていますか? リリース ノートを作成する前に、対象者について考えてください。

2. タイミング: 読者はリリース ノートへいつアクセスしますか? リリース日、またはリリース前ですか? この情報を使用して、レビュー期間などの、リリース ノートの作成スケジュールを設定します。

3. 完了: 何が完了していますか? リリース ノートを、新機能、機能強化、およびバグ修正などのセクションに分けて、完了した内容を一目で確認できるようにします。

4. 編集: リリース ノートに複数の投稿者がいる場合、読者に見られたくない情報が追加されている場合があります。リリース ノートは慎重に編集してください。注: 1 つの機能追加や機能強化についてのスクリーンショットなどの情報が、ほかの機能などに対する情報よりも詳細な場合、その項目の重要性や複雑性を相対的に反映しているように受け取られることがあります。

5. 事実を重視: 事実を記載することが何よりも重要です。リリース ノートは、完全かつ正確である必要があります。 

6. ストーリーとメッセージ: ストーリー展開を使用した説明は、改善点を説明するのに役立ちます。読者に、変更点と、それらが彼らにとって重要な理由をわかりやすく伝えることができます。

開発者と製品マネージャーが継続的に更新できる共有ドキュメントを使用することで、一人のユーザーがドキュメントにかかりきりになることを防ぐことができます。また、リリース ノートは他の情報形式へのハブとしても役立ちます。アプリ内通知、製品ツアー、ブログ投稿、ニュースレター項目、およびヘルプ/サポート資料用のコンテンツを使用しましょう。

まとめ

優れたデザインのリリース ノート ページ テンプレートと、十分に考慮した便利なコンテンツを併用することは、作業を文書化する責務を満たすだけでなく、対象者との関係を深め、反復可能で一貫性があり、優れたコミュニケーションを実現するリリース ノートの作成に役立ちます。

リリース ノート ページ テンプレートに追加するアイテム:

• 目次マクロ: 素早いナビゲーションに役立つ、見出しリンクのリストを作成します。
• Jira 課題マクロ – リリースで解決したすべての課題、および投票数が多い人気の課題の詳細を表示します。
• 抜粋マクロ: リリース ノートの特定のコンテンツを再使用します。
• インクルード ページ マクロ : 複数のページにわたってコンテンツを含めます。
• 水平線: +挿入 メニューを選択して、ページのセクションを分割します。
• 権限と制限: 権限を使用してページを閲覧できるユーザーを制御し、表示制限を調節します。

nifty リリース ノート ページを作成した場合、@Confluence にスクリーンショットをツイートしてプレゼントに応募しましょう!

このページはお役に立ちましたか? Twitter でシェアしてください。