ソフトウェアドキュメント

ソフトウェア ドキュメントは、コンピュータソフトウェアに付属する、またはソース コードに埋め込まれているテキストまたはイラストです。ドキュメントでは、ソフトウェアの動作方法または使用方法が説明されており、異なる役割の人にとっては異なる意味を持つ場合があります。

ドキュメントはソフトウェア エンジニアリングの重要な部分です。ドキュメントの種類には次のものがあります。

  • 要件– システムの属性、機能、特性、または品質を特定するステートメント。これは、今後実装される、または実装されるものの基礎となります。
  • アーキテクチャ/デザイン – ソフトウェアの概要。ソフトウェアコンポーネントの設計に使用される環境と構築原則との関係が含まれます。
  • 技術 – コード、アルゴリズム、インターフェイス、APIのドキュメント。
  • エンド ユーザー– エンド ユーザー、システム管理者、サポート スタッフ向けのマニュアル。
  • マーケティング – 製品をマーケティングする方法と市場の需要の分析。

種類

要件ドキュメント

要件ドキュメントは、特定のソフトウェアが何を行うか、または行うべきかを説明するものです。これは、ソフトウェアがどのように機能するか、またはソフトウェアがどのように動作することを意図しているかを伝えるために、開発全体を通じて使用されます。また、ソフトウェアが何を行うかについての合意または合意の基礎としても使用されます。要件は、エンド ユーザー顧客プロジェクト マネージャー営業マーケティングソフトウェア アーキテクトユーザビリティ エンジニアインタラクション デザイナー開発者、テスターなど、ソフトウェアの制作に関わるすべての人によって作成および消費されます

要件にはさまざまなスタイル、表記、形式があります。要件には、目標のようなもの (分散作業環境など)、設計に近いもの (構成ファイルを右クリックして「ビルド」機能を選択することでビルドを開始できるなど)、およびその中間のものがあります。これらは、自然言語のステートメント、描画された図、詳細な数式、またはそれらすべての組み合わせとして 指定できます。

要件ドキュメントの多様性と複雑さにより、これが困難であることが証明されています。要件は暗黙的であり、明らかにするのが難しい場合があります。どのような種類のドキュメントがどれだけ必要か、アーキテクチャと設計ドキュメントにどの程度を任せられるかを正確に知ることは困難であり、ドキュメントを読んで使用するさまざまな人々を考慮して要件をどのように文書化するかを知ることは困難です。 。したがって、要件文書は不完全である (または存在しない) ことがよくあります。適切な要件文書がなければ、ソフトウェアの変更はより困難になり、その結果、エラーが発生しやすくなり(ソフトウェアの品質が低下し)、時間がかかり(高価になります)ます。

要件文書の必要性は通常、製品の複雑さ、製品の影響、およびソフトウェアの期待寿命に関連しています。ソフトウェアが非常に複雑である場合、または多くの人々によって開発されている場合 (携帯電話ソフトウェアなど)、要件は、何を達成するかをより適切に伝えるのに役立ちます。ソフトウェアが安全性を重視し、人命に悪影響を与える可能性がある場合 (原子力システム、医療機器、機械機器など)、多くの場合、より正式な要件文書が必要になります。ソフトウェアの存続期間が 1 ~ 2 か月のみと予想される場合 (たとえば、特定のキャンペーン専用に開発された非常に小さな携帯電話アプリケーション)、必要な要件ドキュメントはほとんどない場合があります。ソフトウェアが後で構築される最初のリリースである場合、要件ドキュメントは、ソフトウェアの変更を管理し、変更時にソフトウェアに何も問題がないことを確認するときに非常に役立ちます。

従来、要件は要件文書で指定されていました (ワープロ アプリケーションやスプレッドシート アプリケーションを使用するなど)。要件ドキュメント (およびソフトウェア ドキュメント全般) の複雑さの増大と性質の変化を管理するために、データベース中心のシステムと特殊用途の要件管理ツールが提唱されています。

アジャイル ソフトウェア開発では、要件は多くの場合、受け入れ基準を伴うユーザー ストーリーとして表現されます。

アーキテクチャ設計ドキュメント

アーキテクチャ ドキュメント (ソフトウェア アーキテクチャ記述とも呼ばれます) は、特別なタイプの設計ドキュメントです。ある意味、アーキテクチャ ドキュメントはコードからの 3 次派生です (設計ドキュメントは 2 次派生、コード ドキュメントは 1 次派生です)。アーキテクチャ文書には、コード自体に固有の内容はほとんどありません。これらの文書では、特定のルーチンをプログラムする方法や、その特定のルーチンがなぜそのような形で存在するのかさえ説明されておらず、代わりに、そのようなルーチンの存在を動機付ける一般的な要件を列挙しているだけです。優れたアーキテクチャ文書は、詳細は省略されていますが、説明は充実しています。下位レベルの設計のアプローチを提案する可能性がありますが、実際の探査貿易の研究については他の文書に任せます。

別のタイプの設計文書は、比較文書、つまり取引検討書です。これは多くの場合、ホワイトペーパーの形式になりますシステムの 1 つの特定の側面に焦点を当て、代替アプローチを提案します。それは、ユーザー インターフェイス、コード、デザイン、さらにはアーキテクチャ レベルにまで及ぶ可能性があります。状況を概説し、1 つ以上の代替案を説明し、それぞれの長所と短所を列挙します。優れた貿易研究文書は、リサーチに重点を置き、そのアイデアを明確に表現しており(読者を惑わすような難解な専門用語に過度に依存することなく)、最も重要なのは公平です。提供する最善のソリューションのコストを正直かつ明確に説明する必要があります。貿易研究の目的は、特定の観点を押し付けることではなく、最適な解決策を考案することです。結論を述べないこと、またはどの代替案も変更を正当化するほどベースラインよりも十分に優れているとは結論付けないことは完全に許容されます。これはマーケティング手法としてではなく、科学的な取り組みとして取り組む必要があります。

エンタープライズ ソフトウェア開発における設計ドキュメントの非常に重要な部分は、データベース設計ドキュメント (DDD) です。これには、概念的、論理的、物理的な設計要素が含まれています。DDD には、データベースを操作する人々が必要とする正式な情報が含まれています。これを準備する目的は、シーン内のすべてのプレイヤーが使用する共通のソースを作成することです。潜在的なユーザーは次のとおりです。

リレーショナル データベースシステムについて説明する場合、ドキュメントには次の部分を含める必要があります。

  • エンティティ - 関係スキーマ(拡張の有無にかかわらず)。次の情報とその明確な定義が含まれます。
    • エンティティセットとその属性
    • 関係とその属性
    • 各エンティティセットの候補キー
    • 属性およびタプルベースの制約
  • リレーショナル スキーマ。次の情報が含まれます。
    • テーブル、属性、およびそれらのプロパティ
    • ビュー
    • 主キー、外部キーなどの制約
    • 参照制約のカーディナリティ
    • 参照制約のカスケード ポリシー
    • 主キー

シーン内のすべてのアクターが使用するすべての情報を含めることが非常に重要です。データベースにも変更が発生するため、ドキュメントを更新することも非常に重要です。

技術文書

ソース コードに関連付けられたコード ドキュメント ( READMEファイルやAPIドキュメントが含まれる場合があります) が完全であることが重要ですが、冗長すぎて時間がかかりすぎたり、保守が困難になったりしないようにしてください。一般に、API 作成者によって文書化されているソフトウェア アプリケーションまたはソフトウェア製品に固有のさまざまなハウツーおよび概要ドキュメント ガイドが見つかります。このドキュメントは、開発者、テスター、およびエンドユーザーが使用できます。現在、電力、エネルギー、輸送、ネットワーク、航空宇宙、安全、セキュリティ、産業オートメーション、その他のさまざまな分野で多くのハイエンド アプリケーションが見られます。基本レベルと高度なレベルの情報はアーキテクチャの変更に伴って時間の経過とともに変化する可能性があるため、このような組織では技術文書が重要になっています。優れたコードドキュメントの存在により、ソフトウェアのメンテナンスコストが実際に削減されるという証拠があります。[1]

コード文書は多くの場合、リファレンス ガイド形式にまとめられているため、プログラマは任意の関数またはクラスをすばやく検索できます。

ソースコードに埋め込まれた技術文書

多くの場合DoxygenNDocVisual ExpertJavadocJSDocEiffelStudioSandcastleROBODocPODTwinText 、または Universal Report などのツールを使用して、コード ドキュメントを自動生成できます。つまり、コメントやソフトウェア コントラクトを抽出します。可能な場合は、ソース コードから参照し、テキスト ファイルやHTMLファイルなどの形式でリファレンス マニュアルを作成します。

ドキュメントを自動生成するというアイデアは、さまざまな理由からプログラマにとって魅力的です。たとえば、ソース コード自体から (コメントなどを通じて) 抽出されるため、プログラマはコードを参照しながらコードを記述し、ソース コードの作成に使用したのと同じツールを使用してドキュメントを作成できます。これにより、ドキュメントを最新の状態に保つことがはるかに簡単になります。

考えられる欠点は、この種のドキュメントを編集できるのはプログラマだけであり、出力の更新はプログラマに依存していることです (たとえば、毎晩ドキュメントを更新するcron ジョブを実行するなど)。これを短所ではなく長所として特徴付ける人もいます。

読み書きできるプログラミング

尊敬されるコンピューター科学者のドナルド・クヌースは、文書化は非常に困難な後知恵のプロセスになる可能性があると指摘し、ソースコードと同じ時間と場所で記述され、自動手段で抽出される、読み書き可能なプログラミングを提唱しました。プログラミング言語HaskellCoffeeScriptには、単純な形式の読み書き可能なプログラミングのサポートが組み込まれていますが、このサポートは広く使用されていません。

わかりやすいプログラミング

Elucidative Programming は、実際のプログラミングのコンテキストにおける Literate Programming の実践的な応用の結果です。Elucidative パラダイムでは、ソース コードとドキュメントを別々に保存することを提案しています。

多くの場合、ソフトウェア開発者は、ソース ファイル自体には含まれない情報を作成し、アクセスできる必要があります。このような注釈は通常、サードパーティのソース コードが機能的な方法で分析される、コード ウォークや移植などのいくつかのソフトウェア開発活動の一部です。したがって、注釈は、正式な文書システムが進捗を妨げるソフトウェア開発のあらゆる段階で開発者を助けることができます。

ユーザードキュメント

コードドキュメントとは異なり、ユーザードキュメントはプログラムの使用方法を単に説明するだけです。

ソフトウェア ライブラリの場合、コード ドキュメントとユーザー ドキュメントは場合によっては事実上同等であり、結合する価値がありますが、一般的なアプリケーションの場合、これは当てはまらないことがほとんどです。

通常、ユーザー ドキュメントにはプログラムの各機能が説明されており、ユーザーがこれらの機能を実現するのに役立ちます。ユーザードキュメントが混乱しないようにし、最新のものにすることが非常に重要です。ユーザー ドキュメントを特別な方法で編成する必要はありませんが、完全なインデックスを作成することが非常に重要です。一貫性とシンプルさも非常に価値があります。ユーザードキュメントは、ソフトウェアが何を行うかを指定する契約を構成するとみなされます。API ライターは、使用されるソフトウェア アーキテクチャとプログラミング手法をよく知っているため、優れたユーザー ドキュメントを作成することに非常に優れています。テクニカル ライティングも参照してください

ユーザー ドキュメントは、さまざまなオンライン形式や印刷形式で作成できます。[2]ただし、ユーザー ドキュメントを整理するには、大きく 3 つの方法があります。

  1. チュートリアル:チュートリアルアプローチは、新規ユーザーにとって最も有用であると考えられており、特定のタスクを達成するための各ステップをガイドします。[3]
  2. テーマ:章やセクションが 1 つの特定の関心領域に集中するテーマ別アプローチは、中級ユーザーにとってより一般的に使用されます。ユーザーのニーズに応えるために、知識ベースの記事を通じて自分のアイデアを伝えることを好む著者もいます。このアプローチは通常、情報技術などのダイナミックな業界で実践されています[4]
  3. リストまたは参照:最後のタイプの編成原則は、コマンドまたはタスクが単純にアルファベット順または論理的にグループ化され、多くの場合相互参照インデックスを介してリストされるものです。後者のアプローチは、探している情報の種類を正確に知っている上級ユーザーにとって非常に役立ちます。

ソフトウェアのドキュメントに関してユーザーの間でよくある不満は、これら 3 つのアプローチのうち 1 つだけが採用され、他の 2 つはほぼ排除されているということです。パーソナル コンピュータ用に提供されるソフトウェア マニュアルは、コマンドやメニュー項目に関する参照情報のみを提供するオンライン ヘルプ限定されるのが一般的です。新しいユーザーを指導したり、経験豊富なユーザーがプログラムを最大限に活用できるように支援したりする仕事は、民間の発行者に任されており、多くの場合、ソフトウェア開発者から多大な支援を受けています。

ユーザードキュメントの作成

他の形式の技術ドキュメントと同様、優れたユーザー ドキュメントは、組織化された開発プロセスから恩恵を受けます。ユーザー文書の場合、業界で一般的に行われるプロセスは 5 つのステップで構成されます: [5]

  1. ユーザー分析、プロセスの基礎調査段階。[6]
  2. 計画段階、または実際の文書化段階。[7]
  3. ドラフト レビュー。前のステップで作成されたドラフトに対するフィードバックが求められる、説明のないフェーズです。[8]
  4. ユーザビリティ テスト: ドキュメントのユーザビリティが経験的にテストされます。[9]
  5. 編集。ステップ 3 と 4 で収集した情報を使用して最終草案を作成する最後のステップです。

マーケティング文書

多くのアプリケーションでは、偶然の観察者が製品についてより多くの時間を費やして学習できるように、何らかの宣伝資料が必要です。この形式のドキュメントには次の 3 つの目的があります。

  1. 潜在的なユーザーをその製品について興奮させ、その製品にもっと関わりたいという欲求を植え付けるため。
  2. 彼らの期待が彼らが受け取るものと一致するように、製品が正確に何をするのかを彼らに知らせるため。
  3. 他の代替品と比較したこの製品の位置付けを説明するため。

ドキュメンテーションとアジャイル開発に関する論争

「開発者の間で文書化に対する抵抗があることはよく知られており、強調する必要はありません。」[10]これらの方法論では、直接価値をもたらさない不必要なアクティビティを回避しようとするため、この状況はアジャイル ソフトウェア開発 で特に一般的です。具体的には、アジャイル宣言は「包括的なドキュメントよりも実際に動作するソフトウェア」を重視することを提唱していますが、これは「私たちはコーディングにすべての時間を費やしたいのです。本物のプログラマーはドキュメントを書かないことを忘れないでください。」と皮肉的に解釈される可能性があります。[11]

しかし、ソフトウェア エンジニアリングの専門家の間で行われた調査では、アジャイル開発においてドキュメントは決して不必要とは考えられていないことが明らかになりました。しかし、開発には動機付けの問題があり、アジャイル開発に合わせた文書化手法 (たとえば、レピュテーション システムゲーミフィケーションなど) が必要になる可能性があることは認識されています。[12] [13]

こちらも参照

ノート

  1. ^ "コード ドキュメントの予算を獲得する方法".
  2. ^ "RH Earle、MA Rosso、KE Alexander (2015) ソフトウェア ドキュメント ジャンルのユーザー設定。第 33 回コミュニケーションのデザインに関する年次国際会議 (ACM SIGDOC) の議事録"。
  3. ^ ウェルツ、カルロス。「KDE ドキュメント入門」2009 年6 月 15 日に取得
  4. ^ マイクロソフト「ドライバー開発に関するナレッジベースの記事」。マイクロソフト2009 年6 月 15 日に取得
  5. ^ Thomas T. Barker、ソフトウェア ドキュメントの作成、序文、xxiv。『テクニカル コミュニケーション』第 2 版のAllyn & Baconシリーズの一部。Upper Saddle River : Pearson Education、2003 年。ISBN 0321103289 2013 年 5 月 13 日にウェイバック マシンにアーカイブ 
  6. ^ バーカー、pg. 118.
  7. ^ バーカー、pg. 173.
  8. ^ バーカー、pg. 217.
  9. ^ バーカー、pg. 240。
  10. ^ ハーブスレブ、ジェームス D. およびモイトラ、ディペンドラ。掲載: IEEE ソフトウェア、vol. 18、いいえ。2、16-20ページ、2001年3月/4月
  11. ^ ラキーチン、スティーブン。, 「マニフェストは皮肉を誘発する」。IEEE コンピュータ、vol. 34、いいえ。12、p. 2001 年 4 月
  12. ^ プラウス、クリスチャン R.、ゾーヤ ドゥルディク。「アーキテクチャ設計とドキュメント: アジャイル開発における無駄?」出典:ソフトウェアおよびシステム プロセスに関する国際会議(ICSSP)、IEEE、2012 年。
  13. ^ セリック、ブラン。「アジャイルドキュメント、誰か?」掲載: IEEE ソフトウェア、vol. 26、いいえ。6、11-12ページ、2009年
Retrieved from "https://en.wikipedia.org/w/index.php?title=Software_documentation&oldid=1203955941"