すでに開発されているプロジェクトを文書化する方法は？

すでに開発されたプロジェクトを文書化するためにどのオプションが利用できるか知りたいのですが、開発者は1ページも文書を作成しませんでした。

このプロジェクトには、過去2年間にこのプロジェクトに携わった開発者によって作成および変更された機能を備えた多くのスクリプトページ以外の詳細はありません。私が持っているのは、データベーススキーマとプロジェクトファイルだけです。このプロジェクトを組織し、文書化する方法があるかどうかを知りたいので、将来このプロジェクトに取り組む開発者に役立つようにします。

このプロジェクトはPHPとMySQLで開発されました。関数のコメントが不十分であるため、doxygenで実行すると良い結果が得られません。

誰がドキュメントを読むのですか？ドキュメントは何に使用されますか？これらは答えるべき最も重要な質問です。たとえば、メンテナンス開発者向けのドキュメントは構造に焦点を当てるのに対し、製品と統合する開発者向けのドキュメントはWebサービスとデータベース構造に焦点を当てます。

一般に、必要なだけドキュメントを作成し、それ以上は行いません。多くの組織はドキュメントが必要であると誰かが主張しているため、ドキュメントが必要ですが、ドキュメントはほこりを集めることになります。

人々が実際にドキュメントを使用すると仮定して、コードとデータベースを最小レベルにキャプチャしようとしないでください。開発者は、特徴のコードを調べます。代わりに、コードでは明らかではない詳細に焦点を当てます。例：

1. ユースケース製品が満たしています。これは、製品の年齢を考えると難しいかもしれませんが、製品の意図を把握することは、非技術的な読者やテスターに​​とって重要なコンテキストを与えます。市場の競合他社は誰ですか？製品の範囲から除外されるものはありますか？
2. 明確な非機能要件。たとえば、製品は特定のボリュームを処理するように作成されていましたか？データは何歳になりますか？キャッシングはどこで使用されますか？ユーザーはどのように認証されますか？アクセス制御はどのように機能しますか？
3. コンテキストダイアグラム監視など、他のデータベースなどのシステムは、認証元、バックアップとの相互作用を示します。
4. （既知の場合）リスクと、それらがどのように軽減されたかを決定表とともに確認します。振り返ってみると、これはおそらく困難ですが、多くの場合、設計に影響を与える重要な決定があります。知っていることをすべてキャプチャします。
5. 一般的な設計パターンまたは設計ガイドライン。たとえば、データベースにアクセスする標準的な方法はありますか？コーディングまたは命名の標準はありますか？
6. 通常、フローチャートまたはUMLアクティビティまたはシーケンス図を使用したクリティカルコードパス。プロジェクトには何もないかもしれませんが、これらは通常、ビジネスユーザーが明確にしたものです。

この情報がすべて入手できない場合でも、今すぐ開始してください。あなたの後に来る開発者はあなたに感謝します。

優れた自動化された単体テストまたはテストケースも有用なドキュメントになりますが、それほど技術的な人にはアクセスしにくいものです。

ドキュメントを含めるために文化的変化を起こす必要があるようにも聞こえます。小さく始めますが、理想的には、少なくとも最低限のレベルのドキュメントが作成されるまで、プロジェクトを「完了」させないでください。上記はあなたが制御できるものであるため、これはおそらく最も難しいステップです。これは、他の人が買う必要があるものです。ただし、特にやりがいのある次のプロジェクトに優れたドキュメントが付属している場合は、最もやりがいがあります。

過去には、さまざまな製品所有者やパワーユーザーと一緒に座って、主なユースケースを確認し、一連のテストでこれらを文書化することで、このような状況を管理していました。将来変更を開始するときに、これらをシステムのベースラインとして使用できます。これは、所有者やユースケースがなく、削除される可能性のあるシステムの領域を識別するのにも役立ちます。

それはすべてシステムのサイズに本当に依存します。これが多くの異なる利害関係者を含む複雑なシステムである場合、存在する機能とそれらが満たされる場所を詳述する高レベルのコンポーネント図を作成できます。これは、システム設計のアーキテクチャ上の問題を特定するのに非常に役立ちます。

一般に、古くなったドキュメントは時代遅れになり、将来的に開発者をリードする可能性があるため、古いドキュメントを避けることをお勧めします。私は常に、システムの進化に応じて維持されるテスト形式の生きたドキュメントを作成しようとしています。

まず最初に、ターゲットオーディエンスは誰ですか？将来の開発者や他のビジネスマンですか？その質問への答えを念頭に置いて：

他の人が言ったように、最初に必要なのは高レベルの説明です。より広い体系でシステムが何をしようとしているのかを説明します。実行対象、ネットワークへの適合性、および他のシステムとの通信方法を説明します。次に、各画面を調べてスクリーンショットを作成し、画面の機能とシステムの他の部分との相互作用について簡単に説明します。開発者向けの場合は、アプリを初めて説明するように会話を続けます。結局のところ、それがドキュメントのポイントです（私は推測します）。

複雑な処理やロジックには、状態図、データフロー図、またはシーケンス図を使用します。確実にエンティティ図を作成し、次にDBスキーマ設計を行います（2つの異なること！）。基本的なクラス図かもしれませんが、シンプルに保ち、関心のある主なものだけに注意してください。開発者はコードを見ることでそのようなものを把握できます。

開始するのに問題がある場合は、すぐ隣の部屋に別の開発者がいるように見せてください。システムの最初のことを知らない開発者がいます。その後、説明を開始し、あなたの言うことを書き留めてください:)

これまでの提案はすべて良い提案ですが、ユーザーコミュニティがアドホックなドキュメントを自分で作成したかどうかを調査することも検討します。質問では、「製品」のバージョン（2年間存在する）がユーザーにリリースされたことがあるかどうかを指定しませんでした。それが使用されていて、公式文書がない場合、文書は不要であるか、または初歩的であるがユーザーによって不可欠であると思われる「非公式」文書がどこかにあります。重要なAPIを表す可能性のあるアーティファクトの検索、フォーラムの検索、パワーユーザーへの質問、質問と回答のサイトの検索をWebで試してください。可能であれば、技術的またはビジネス上のニーズを満たすドキュメントを作成してください。

問題は、それを現在のままにするのか、それともあるべきなのかを文書化したいですか？

あなたの質問から私が読んだことは、あなたはAPIドキュメントについて考えており、それほど多くのユーザードキュメントではなく、コードはおそらくあまりよく維持されておらず、暗号化されていないということです。

今すぐ文書化すると、コードがリファクタリングされると、ほとんどの作業が破棄されることになります。

私は次のアプローチを取ります。

• 一般的なベストプラクティスを順守することにより、ドキュメントを可能な限り不要にします。直感的に理解できる適切なクラス名、メソッド名、変数名を選択してください
• 巨大なモンスターのクラスや機能を意味のある場所で分解する
• PHPdocコメントを使用する-ツールを使用してAPIドキュメントを作成できます
• テストを作成する：テストは、コードが何をすべきかを理解または定義するのに役立ちます。

今、あなたはまだ文書化されていないものがあります：これは一般的な概念、アーキテクチャなどかもしれません。このために、私は実際にドキュメントを書きます-しかし、本当に有用で役立つものだけを書きます。