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

ウィキペディアから、無料の百科事典
ナビゲーションにジャンプ 検索にジャンプ

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

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

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

要件ドキュメント

要件ドキュメントは、特定のソフトウェアが実行する、または実行する必要があることの説明です。これは、ソフトウェアがどのように機能するか、またはソフトウェアがどのように動作することを意図しているかを伝えるために、開発全体で使用されます。また、ソフトウェアが何をするかについての合意または合意の基盤としても使用されます。要件は、エンドユーザー顧客プロジェクトマネージャー販売マーケティングソフトウェアアーキテクトユーザビリティエンジニアインタラクションデザイナー開発者テスター

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

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

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

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

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

アーキテクチャドキュメント(ソフトウェアアーキテクチャの説明とも呼ばれます)は、特殊なタイプの設計ドキュメントです。ある意味で、アーキテクチャドキュメントはコードからの3次派生物です(設計ドキュメントは2次派生物であり、コードド​​キュメントは1番目です)。アーキテクチャドキュメントには、コード自体に固有のものはほとんどありません。これらのドキュメントでは、特定のルーチンをプログラムする方法や、その特定のルーチンがそのような形式で存在する理由については説明していませんが、その代わりに、そのようなルーチンの存在を動機付ける一般的な要件を示しています。優れたアーキテクチャドキュメントは、詳細が不足していますが、説明が豊富です。それはより低いレベルの設計のためのアプローチを示唆するかもしれませんが、実際の探鉱貿易研究は他の文書に任せます。

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

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

リレーショナルデータベースシステムについて話すとき、ドキュメントには次の部分が含まれている必要があります。

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

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

技術文書

ソースコードに関連付けられているコードドキュメント(READMEファイルやAPIドキュメントを含む場合があります)は完全であることが重要ですが、過度に時間がかかるか、保守が困難になるほど冗長ではありません。さまざまなハウツーおよび概要のドキュメントガイドは、APIライターによってドキュメント化されているソフトウェアアプリケーションまたはソフトウェア製品に固有のものとして一般的に見られます。このドキュメントは、開発者、テスター、およびエンドユーザーが使用できます。今日、多くのハイエンドアプリケーションが、電力、エネルギー、輸送、ネットワーク、航空宇宙、安全、セキュリティ、産業自動化、およびその他のさまざまな分野で見られます。技術文書は、アーキテクチャの変更に伴って情報の基本レベルと高度レベルが一定期間にわたって変更される可能性があるため、このような組織内で重要になっています。

コードドキュメントは多くの場合、リファレンスガイドスタイルに編成されているため、プログラマーは任意の関数またはクラスをすばやく検索できます。

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

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

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

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

文芸的プログラミング

尊敬されているコンピューター科学者のドナルド・クヌースは、ドキュメンテーションは非常に難しい後付けプロセスである可能性があることを指摘し、ソースコードと同時に書かれ、自動手段によって抽出される文芸的プログラミングを提唱しました。プログラミング言語のHaskellCoffeeScriptには、単純な形式の文芸的プログラミングのサポートが組み込まれていますが、このサポートは広く使用されていません。

解明的プログラミング

解明的プログラミングは、実際のプログラミングコンテキストでの文芸的プログラミングの実用的なアプリケーションの結果です。解明パラダイムは、ソースコードとドキュメントを別々に保存することを提案しています。

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

ユーザードキュメント

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

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

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

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

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

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

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

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

  1. ユーザー分析、プロセスの基礎研究フェーズ。[5]
  2. 計画、または実際の文書化フェーズ。[6]
  3. ドラフトレビュー。前のステップで作成されたドラフトについてフィードバックが求められる自明のフェーズ。[7]
  4. 使いやすさのテスト。これにより、ドキュメントの使いやすさが経験的にテストされます。[8]
  5. 編集、ステップ3と4で収集された情報を使用して、最終ドラフトを作成する最終ステップ。

ドキュメントとアジャイル開発の論争

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

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

マーケティングドキュメント

多くのアプリケーションでは、カジュアルなオブザーバーが製品についてより多くの時間を費やすように促すために、いくつかの販促資料を用意する必要があります。この形式のドキュメントには、次の3つの目的があります。

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

も参照してください

メモ

  1. ^ 「RHEarle、MA Rosso、KE Alexander(2015)ソフトウェアドキュメンテーションジャンルのユーザー設定。コミュニケーションの設計に関する第33回年次国際会議(ACM SIGDOC)の議事録」
  2. ^ Woelz、Carlos。「KDEドキュメンテーション入門書」2009年6月15日取得
  3. ^ マイクロソフト「ドライバー開発のための知識ベースの記事」2009年6月15日取得
  4. ^ Thomas T. Barker、ソフトウェアドキュメントの作成、序文、xxiv。テクニカルコミュニケーションのAllyn&Baconシリーズの一部アッパーサドルリバーピアソンエデュケーション、2003年。ISBN0321103289 2013年5月13日、ウェイバックマシンでアーカイブ 
  5. ^ バーカー、ページ。118。
  6. ^ バーカー、ページ。173。
  7. ^ バーカー、ページ。217。
  8. ^ バーカー、ページ。240。
  9. ^ Herbsleb、James D.およびMoitra、Dependra。In: IEEE Software、vol。18、いいえ。2、pp.16-20、2001年3月/ 4月
  10. ^ ラキティン、スティーブン。「マニフェストは冷笑主義を誘発します。」IEEE Computer、vol。34、いいえ。12、p。2001年4月4日
  11. ^ Prause、Christian R.、およびZoyaDurdik。「アーキテクチャの設計と文書化:アジャイル開発の無駄?」In: International Conference on Software and System Process(ICSSP)、IEEE、2012年。
  12. ^ セリック、ブラン。「アジャイルドキュメント、誰か?」In: IEEE Software、vol。26、いいえ。6、pp。11-12、2009