すでに開発されているプロジェクトを文書化する方法は？
既に開発されたプロジェクトを文書化するために利用できるオプションを知りたいのです。開発に携わった開発者は1ページの文書も書かなかったからです。
このプロジェクトには、過去2年間からこのプロジェクトに取り組んだ開発者によって作成および変更された機能を備えたスクリプトの多くのページ以外の詳細はありません。私が持っているのは、データベーススキーマとプロジェクトファイルだけです。今後このプロジェクトに取り組む開発者にとって役立つように、このプロジェクトを整理して文書化する方法があるかどうか知りたいのですが。
プロジェクトはPHP=およびMySQLで開発されました。関数のコメントが不十分であるため、doxygenで実行すると良い結果が得られません。
誰がドキュメントを読みますか？ドキュメントは何のために使用されますか？これらは回答する最も重要な質問です。たとえば、メンテナンス開発者向けのドキュメントは構造に重点を置き、製品と統合する開発者向けのドキュメントはWebサービスとデータベース構造に重点を置きます。
一般に、必要なだけのドキュメントを作成し、それ以上はしないでください。多くの組織は、誰かがそれがベストプラクティスであると主張したので、ドキュメントを必要としますが、ドキュメントはほこりを集めることになります。
人々が実際にドキュメントを使用することを想定して、コードとデータベースを最小レベルにキャプチャしようとしないでください。開発者はマニューシャのコードを確認します。代わりに、コードでは明らかではない詳細に焦点を当てます、たとえば：
- 使用例製品が適合します。製品の古さを考えるとこれは難しいかもしれませんが、製品が何をするつもりなのかを把握することは、技術者ではない読者やテスターに重要なコンテキストを与えます。市場の競争相手は誰か（もしあれば）？製品の範囲から除外されるものはありますか？
- 明確な非機能要件。たとえば、製品は特定のボリュームを処理するように作成されましたか？データは何歳ですか？キャッシングはどこで使用されますか？ユーザーはどのように認証されますか？アクセス制御はどのように機能しますか？
- A コンテキスト図データベース、認証ソース、バックアップ、監視など、他のシステムとの相互作用を示します。
- （既知の場合）リスクおよび決定レジスターとともにそれらがどのように軽減されたか。これはおそらく振り返ってみると難しいでしょうが、設計に影響を与える重要な決定がしばしばあります。あなたが知っているものをキャプチャします。
- 一般的な設計パターンまたは設計ガイドライン。たとえば、データベースにアクセスする標準的な方法はありますか？コーディングまたは命名の基準はありますか？
- クリティカルコードパス、通常はフローチャートまたはUMLアクティビティまたはシーケンス図を使用します。プロジェクトには何もないかもしれませんが、これらは通常、ビジネスユーザーが明確に述べたものです。
このすべての情報が利用できない場合でも、今すぐ開始。あなたの後に来る開発者はあなたに感謝します。
自動化された優れた単体テストまたはテストケースは、あまり技術的でない人がアクセスすることは困難ですが、有用なドキュメントになることもあります。
ドキュメントを含めるための文化的な変更を行う必要があるようにも聞こえます。小さなものから始めますが、理想的には、プロジェクトは、最低限のレベルのドキュメントが作成されるまで「完了」しないでください。上記はあなたが制御できるものであるため、これはおそらく最も難しいステップです。これは他の人が理解しなければならないものです。ただし、特に次のプロジェクトに優れたドキュメントが付属している場合は、これが最もやりがいのある作業になることもあります。
過去に私は、さまざまな製品の所有者やパワーユーザーと一緒に座り、主要な使用例を検討し、これらを一連のテストで文書化することによって、このような状況を管理していました。これらは、将来変更を始めるときに、システムのベースラインとして使用できます。これは、所有者またはユースケースがなく、削除される可能性があるシステムの領域を識別するのにも役立ちます。
それはすべて実際にシステムのサイズに依存します。これがさまざまな利害関係者がいる複雑なシステムである場合、どのような機能が存在し、どこで満たされているのかを詳述した高レベルのコンポーネント図を作成できます。これは、システム設計でアーキテクチャの問題を特定するのに非常に役立ちます。
古くなり、将来的に開発者のミスリードとなるため、一般的には、古い形式のドキュメントは避けることをお勧めします。私は常に、システムの進化に合わせて維持されるテストの形で、生きたドキュメントを作成するようにしています。
まず最初に、あなたのターゲットオーディエンスは誰ですか？将来の開発者や他のビジネスマン？その質問への答えを念頭に置いて：
他の人が言ったように、高レベルの説明が最初に必要です。より広範なスキームでシステムが何をしようとしているのかを説明します。何が実行されているか、どのようにネットワークに適合し、他のシステムと通信するかを説明します。次に、各画面を確認し、スクリーンショットを撮って、画面の機能、およびシステムの他の部分との相互作用について簡単に説明します。開発者向けの場合は、アプリを初めて説明するときのように、会話を続けます。結局、それがドキュメントのポイントです（私はそう思います）。
複雑な処理やロジックはすべて、状態図、データフロー図、またはシーケンス図を使用します。確かにエンティティダイアグラムを実行し、次にDBスキーマを設計します（2つの異なるもの！）。おそらく基本的なクラス図かもしれませんが、単純にしてください。興味のある主要なものだけに注意してください。開発者はコードを見ればそのことを理解できます。
開始時に問題が発生した場合は、すぐ隣の部屋に、システムの最初のことを知らない別の開発者がいると仮定してください。次に説明を開始し、あなたの言うことを書き留めます:)
問題は、それを現状のまま、または本来あるべき状態で文書化したいですか。
私があなたの質問から読んだのは、APIドキュメントについて考えているのであって、ユーザードキュメントについてはそれほど考えていないということです。
あなたが今文書化すると、コードがリファクタリングされると、あなたはあなたの仕事のほとんどを捨ててしまうでしょう。
私は次のアプローチを取ります：
- 一般的なベストプラクティスを順守することにより、ドキュメントをできるだけ不要にします。直感的に理解できる適切なクラス名、メソッド名、変数名を選択してください
- 巨大なモンスターのクラスや機能を破壊する
- pHPdocコメントを使用-ツールを使用してAPIドキュメントを作成できます
- そのためのテストを書く：テストは、コードが何をすべきかを理解または定義するのに役立ちます。
今、あなたはまだ文書化されていないものがあります：これは一般的な概念、アーキテクチャなどかもしれません。これのために、私は実際に文書を書きますが、本当に有用で役立つものだけを書きます。
これまでの提案はすべて良いものですが、ユーザーコミュニティがアドホックドキュメントを自分で作成したかどうかを調査することも検討します。あなたの質問には、「製品」の任意のバージョン（2年間存在）がユーザーにリリースされたことがあるかどうかは指定されていません。それが使用されていて、公式のドキュメントがない場合、ドキュメントは不要であるか、初歩的であるかもしれないが、おそらくユーザーによって不可欠であると思われるどこかに「非公式」のドキュメントがあります。重要なAPIを表す可能性のあるアーティファクトをWebで検索し、フォーラムを検索し、パワーユーザーに質問し、質問と回答のサイトを検索してください。可能であれば、技術的またはビジネス上のニーズを満たしているドキュメントを作成してください。