docs-release-maintenance

ドキュメントのリリースとメンテナンス

このスキルは、ソフトウェアのリリースおよびメンテナンスのライフサイクルに合わせて開発者向けドキュメントを維持するために使用します。公開準備、オーナーシップ、自動化、最新性、責任ある非推奨化や削除を扱います。

このスキルは、Docs for Developers: An Engineer's Field Guide to Technical Writing、特に第7章「ドキュメントの公開」と第11章「ドキュメントのメンテナンスと非推奨化」に基づいています。また、Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group のガイダンスを言い換えて拡張しており、特に第10章「既存コンテンツのメンテナンス」、第25章「SaaS ドキュメントの作成」、第2章「アジャイル」を参考にしています。書籍の文章をユーザー向けの出力にコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、必要最小限の参考資料を選びます。
2. リリース、影響を受けるユーザー、ドキュメントのオーナー、信頼できる情報源、公開経路を特定します。
3. リリースまたはメンテナンスの計画には、workflows/plan-doc-release-maintenance.md を使用します。
4. 古くなったコンテンツ、パッチの蓄積、依存関係の更新に伴って重点的な見直しが必要な場合は、workflows/refresh-existing-docs.md を使用します。
5. ドキュメントの公開、レビュー、テスト、告知、非推奨化をコード変更に合わせます。
6. 既知の手間を省く自動化を優先します。不明確なプロセスは自動化しないでください。

デフォルトの出力

リリースまたはメンテナンス作業を計画する場合は、次の内容を返します。

1. リリースまたはメンテナンスの範囲 - コードや製品の変更と、影響を受けるドキュメント。
2. ユーザーへの影響 - 影響を受けるユーザーと、必要な対応。
3. 公開チェックリスト - オーナー、レビュアー、承認、テスト、提供、告知。
4. メンテナンス計画 - オーナー、最新性の確認、リンクの確認、リンティング、生成されたリファレンス。
5. 非推奨化または削除の計画 - 警告、代替案、移行ガイド、リダイレクト、実施時期。
6. リスクと阻害要因 - 未検証の事実、オーナーの不在、自動化の不足。

内容

必要なこと	まず確認する項目
リリースとメンテナンスの概念を理解する	references/core/knowledge.md
ライフサイクルのルールを適用する	references/core/knowledge.md
チェックリストの例を見る	references/core/knowledge.md
リリース、メンテナンス、非推奨化を計画する	workflows/plan-doc-release-maintenance.md
既存のドキュメントを見直す	workflows/refresh-existing-docs.md
タスクに応じて参照先を選ぶ	guidelines.md

基本方針

• ドキュメントは、説明対象のソフトウェア変更と同時にリリースする必要があります。
• メンテナンス対象のすべてのドキュメントには、オーナーまたは信頼できる情報源が必要です。
• 自動化は、理解された手作業のプロセスに基づいて行う必要があります。
• メンテナンス作業では、コンテンツにパッチを適用する前に範囲を評価する必要があります。
• 非推奨化と削除は、単なる整理作業ではなく、ユーザーへのコミュニケーションの問題です。