- この記事の原著者：グ兄の弟
- 著者ブログアドレス：http://blog.csdn.net/lfdfhl
- この記事の参考資料: 『Software Documentation Writing Tutorial』（Electronic Industry Press、Ma Ping、Huang Dongmei 編）
文書化戦略を策定する
文書化戦略は、下位の開発部門または開発者に指導を提供するために、上位 (上級) マネージャーによって策定されます。ポリシーは、何をどのように行うかという詳細な仕様ではなく、主な方向性を指定します。一般に、文書化ポリシーのステートメントは明確で全員に伝達され、ポリシーが全員に実装されるように理解される必要があります。
効果的な文書化戦略をサポートする基本的な条件は次のとおりです。
- ドキュメントはソフトウェア ライフサイクル全体をカバーする必要がある
ドキュメントはプロジェクトの初期段階で必要であり、ソフトウェア開発プロセス全体を通じて利用可能で保守可能でなければなりません。開発完了後、ドキュメントはソフトウェアの使用、保守、拡張、変換、または送信を満たしている必要があります。 - 文書は管理可能である必要がある
文書の取得と保守を指示および制御するには、マネージャーとリリース専門家は、製品、スケジュール、信頼性、リソース、品質保証、およびレビュー手順を文書化するための詳細な計画概要を作成する必要があります。 - ドキュメントは対象読者に適したものでなければなりません
。対象読者は、マネージャー、アナリスト、コンピュータの経験のない専門家、保守担当者、事務担当者などです。実行するタスクに応じて、さまざまなマテリアル表現とさまざまな詳細レベルが必要になります。配布スペシャリストは、さまざまな対象者向けにさまざまなタイプのドキュメントをデザインする責任を負います。 - ドキュメンテーションの効果は、ソフトウェア開発プロセス全体を通じて実行される必要があります
。ソフトウェア開発プロセス全体を通じて、ドキュメンテーションの機能と制限が完全に反映される必要があります。つまり、ドキュメンテーションは開発プロセス全体をガイドする必要があります。 - 文書化標準を特定して使用する必要があり
、可能な限り既存の標準を採用する必要があり、必要に応じて適用可能な標準またはガイドラインを開発する必要があります。
ソフトウェア製品の開発と保守を支援するツール (ドキュメントを含む) を指定する必要があります。したがって、可能な限り工具を使用することが経済的で実現可能です
文書標準の開発
開発文書の作成には、可能な限り現行の国内標準および国際標準を採用する必要があり、現行標準が適用できない場合には、組織は独自の標準を策定する必要があります。
1. ソフトウェア ライフサイクル モデルを選択する
一部の既存のソフトウェア ライフ サイクル モデルには、フェーズごとに異なる語彙があり、ソフトウェア ドキュメントの観点からは、フェーズと対応するドキュメントが明確に定義され、計画されており、従うことができる限り、どのモデルを使用するかは問題ではありません。特定のソフトウェア プロジェクト向け。したがって、管理者はソフトウェア ライフサイクル モデルを選択し、それが組織内で適用できることを確認する必要があります。
マネージャーは、実行されるフェーズの定義と対応するタスクが、ソフトウェア プロジェクトの進行状況を監視するのに役立ちます。特定のフェーズに対応して作成された文書は、そのフェーズのレビュー、合格、完了のチェックポイントとして使用でき、次のフェーズが始まる前に行う必要があります。
2. 文書の種類と内容を指定する
主要な種類のソフトウェア ドキュメントの概要を以下に示します。この概要は網羅的または決定的なものではありませんが、主要な種類のソフトウェア ドキュメントのチェックリストとして適しています。むしろ、管理者は標準ドキュメント タイプをいつ定義するかを指定する必要があります。
ソフトウェア ドキュメントは、次の 3 つのカテゴリに分類されます。
• 開発ドキュメント - 開発プロセス自体について説明します。
• ガバナンス文書 - プロジェクト管理のための情報を記録します。
• ユーザードキュメント – ユーザーが必要とする情報を文書化します。
• 文書の品質レベルの決定
開発ドキュメントのガイドライン
規制、伝統的な慣行、または契約上の要件に従って文書を作成するだけでは十分ではありません。マネージャーは、文書の品質要件と、品質要件を達成および保証する方法も決定する必要があります。
品質要件の決定は、利用可能なリソース、プロジェクトの規模とリスクに依存し、製品の各ドキュメントの形式と詳細レベルは明確に指定できます。
各文書の品質は文書計画期間中に明確に定義する必要があり、文書の品質は文書の形式と列挙された要件に応じて 4 つのレベルに分けることができます。
最小ドキュメント (レベル 1 ドキュメント): レベル 1 ドキュメントは、開発作業負荷が 1 人月未満の自己使用プログラムに適しています。この文書には、プログラムのリスト、開発記録、テストデータ、およびプログラムの概要が含まれている必要があります。
内部ドキュメント (レベル 2 ドキュメント): レベル 2 ドキュメントは、注意深く調査した結果、他のユーザーとリソースを共有していないと思われる特殊なプログラムについて利用できます。レベル 1 のドキュメントで提供される情報に加えて、レベル 2 のドキュメントには、ユーザーがプログラムをインストールして使用するのに役立つ十分なメモがプログラム リスト内に含まれています。
実用的なドキュメント (レベル 3 ドキュメント): レベル 3 ドキュメントは、同じ組織内の複数の人が共同開発したプログラム、または他の組織が使用できるプログラムに適しています。
正式なドキュメント (レベル 4 ドキュメント): レベル 4 ドキュメントは、一般用途向けに正式にリリースされたソフトウェア製品に適しています。レベル 4 の文書は、重要な手順や給与計算などの反復的な管理アプリケーションの性質の手順に必要です。レベル 4 の文書は GB8567 の関連規定に準拠しています。
品質に関する考慮事項には、ドキュメントの構造とドキュメントの内容の両方が含まれます。文書の内容は、正確さ、完全性、明瞭さについて判断される場合があります。一方、文書の構造は、個々のコンポーネントの順序と全体の配置の単純さによって決まります。これら 4 つの品質レベルを達成するには、必要な投資とリソースが段階的に増加し、望ましい品質レベルが確実に達成されるように、品質保証組織が適切な管理上の立場にある必要があります。