「ドキュメント」を正確に構成するものは何ですか？

ソフトウェア製品の「ドキュメント」と言うとき、それには何が含まれ、何が含まれてはいけませんか？

たとえば、最近の質問で、コメントをドキュメントと見なすかどうかを尋ねましたか？

しかし、これが同様に有効な質問である他の多くの領域があります、いくつかは他のものより明白です：

• マニュアル（明らかに）
• リリースノート？
• チュートリアル
• コメント
• 他のもの？

線はどこに描かれますか。たとえば、「チュートリアル」がドキュメントの場合、「ビデオチュートリアル」のドキュメントですか、それとも別のものですか？

一般に、ソフトウェアの何かは、実装、テスト、および文書化されるまで「完了」しません。したがって、この質問は、「完了」したことを検討するために文書化の一部としてどのようなことを検討する必要があります。

_{私たちの会議での最近の顧客フィードバックからの質問は、私たちのドキュメントがより多くの「サンプル」を必要としていたことを示唆しています。}

_{対象者：データベース、プログラミング言語、および関連ツール（前述のDBの管理クライアントなど）を使用するソフトウェア開発者}

文書化の目的は、ソフトウェア製品を説明および説明することです。そのため、その説明または説明に寄与する一連の成果物として文書化を定義できます。関連するアクションをドキュメントの一部とは考えないでしょう。たとえば、1週間のトレーニングコースはドキュメントではありませんが、コース資料はあります。5分間のホワイトボードチャットはドキュメントではなく、ホワイトボードの画像です。

目標（ソフトウェアの説明）を念頭に置いて、顧客が説明に満足したらドキュメントが完成します。顧客がソフトウェアに満足したらソフトウェアが完成するのと同じです。ドキュメンテーションの顧客は、ソフトウェアの代金を支払う顧客と常に同じではないことに注意してください。サポート担当者、テスター、営業担当者などはすべて、ソフトウェアの機能と動作をある程度理解する必要があります。

これは、ドキュメントに含めるべきものの境界がどこにあるかを理解するのに役立ちます。「リーダー」を便利な速記として使用しますが、ビデオまたはオーディオを含めることができます。読者がソフトウェアについて必要な情報を得るのに役立つものは、使用できるドキュメントであり、他のすべてはそうではありません。顧客がすべてのユースケースの詳細なウォークスルーを必要とする場合、それはドキュメントの一部である必要があります。開発者は、おそらくソースコード、バージョン管理リポジトリに関する情報、およびビルド手順を必要とします。それはそれらのドキュメントですが、上記のように、それは顧客のドキュメントの一部ではありません。

会議での会話から間違った部分を取り除いたと思います。最新のソフトウェア開発方法論では、開発チームは顧客（または顧客プロキシとして機能する製品所有者）と密接に連携する必要があると主張しています。提供されるすべての作業について、「完了」の定義は、チームと顧客の間で交渉され、ソフトウェアの開発中に繰り返し行われます。

あなたが遭遇した問題は、顧客が必要と想定したものと、彼らがあなたが配達することを期待したものとの間に断線があったということです。

ドキュメンテーションとは何ですか...まあ、それはあなたがリストしたほとんどすべてであり、おそらくあなたがしなかった他のいくつかのものです。ただし、プロジェクトに必要なドキュメントの量は誰にもわかりません。プロジェクトはそれぞれ異なり、プロジェクトに必要なドキュメントのレベルと種類を決定するのは、チーム、製品所有者、および顧客次第です。

作用するいくつかの要因：

• ソフトウェアv1.0を開発していて、他のプロジェクトに移行していますか、それともこの継続中の長期プロジェクトですか？後者の場合、コメント/設計ドキュメントがより重要になります。一方、顧客がママとポップなドーナツショップであり、あなたが決して見ないであろうウェブサイトを書いているなら...まあ、コードのドキュメントはいいが、それほど重要ではないと思います。
• 病院で心拍数モニターを制御するモバイルゲームまたはソフトウェアを開発していますか。より多くのドキュメントがある「完了」の定義があるのはどれでしょうか？
• あなたの顧客は典型的なエンドユーザーですか、それとも他の開発者ですか？公開しているAPI / SDKがありますか？
• 顧客の専門知識のレベルはどのくらいですか？これは、ビデオチュートリアルの選択と、書かれた素材の選択、何らかのインタラクティブなチュートリアルアプリの選択に影響します。
• 顧客は、バージョンごとに何が変わったのか気にしていますか。ある人はそうします。ほとんどありません。少数の人にとっては、注意するのは法律（またはそれに近い）です。

ドキュメントは、変更せずに読むことを目的としています。

目的ベースの定義で間違いを犯すことはできないと思いますが、目的を適切に定義する場合に限ります。

• ^{文書化の目的を適切に定義することは非常に簡単ではありません。自然に頭に浮かぶ単純な（必要に応じて単純な）区別は、ドキュメントは読み取りを目的とするすべてのものであり、一方、比較のためにコードはコンピューターの実行を目的とするものであるということです。表面的にはいいですね。しかし、深く掘り下げると非常にいものになります。
   
  つまり、優れたコードでは、実行の正確性とともに読みやすさの問題が考慮されます。これにより、ドキュメントの定義において「読みやすさ」の区別がほとんど役に立たなくなります。あなたが言及した
   
  まさにそのサンプルは、何が悪いのかを示しています。クライアントは通常、これらが明確に書かれていることを期待し、正しく実行します。可読性または正確性のいずれかを妥協すると、顧客からの苦情の滝がもたらされる可能性があります。素朴な区別は、サンプルがコードなのかドキュメントなのかを判断するのに役立ちません。オープンソースでの
   
  作業を想像すると、素朴な区別を使用すると、さらに面倒になります。あなたはそれをダウンロードし、ビルドし、実行します-あなたはそれを読んでいない、それはちょうど正しいコードですか？待ってください、何かがどういうわけか間違っていて、そこで何が起こっているのかを読むためにコードに行きます...ちょっと読んで実行しないでください-このドキュメントは今ですか？そして最後に、ソースのバグを見つけて修正します-これが実際にコードであり、それを修正するためにどれだけ注意深く読んでも、通常ドキュメントと呼ばれるものではありません。}

提供しようとしている「サンプル」については、「変更不可の読み取り」の区別が非常に重要になることがあります。

文書化されたリファレンス環境で、変更せずに実行したときにサンプルが失敗した場合、それはあなたのバグです。

現在、変更されたサンプルまたは環境に問題がある場合、それはもうあなたのせいではありません-ドキュメントは変更を目的としていないため、ドキュメントにバグがないことを意味します。そのような場合にユーザーに提供するものは何でも、バグ修正ではなくサポートカテゴリに分類されます。

「どうやって...」という質問に答えるのはドキュメントです。

開発者にとっては、要件仕様（「書くべき内容を知る方法」）、設計ドキュメント（「要件に対処する方法」）、トレーサビリティマトリックス（「設計がすべての要件に対処することを知る方法」）、テスト計画（「コードがどのように機能するかを知る方法」）、単体テスト（「要件Xを満たしていることを知る方法」）、インラインコメント（「次の貧しいschlubがこれを書いた理由を理解する方法を確認する方法」方法」、展開手順（「この製品をインストール用にパッケージ化する方法」）など。

ユーザーにとっては、ユーザーマニュアル（「ソフトウェアの使用方法」）、チュートリアル（「この特定の機能の使用方法」）、リリースノート（「修正されたバグ /新しいバグ機能の確認方法」）「追加」）など