如何记录已经开发的项目？

我想知道哪些选项可用于记录已开发的项目，因为从事该项目的开发人员甚至没有编写任何页面的文档。

该项目没有其他细节，只有许多页面的脚本具有过去两年来从事该项目的开发人员编写和修改的功能。我所拥有的只是数据库架构和项目文件。我想知道是否有任何方法可以组织这个项目并将其记录下来，从而对将来将从事此项目的开发人员有所帮助。

该项目是使用PHP和MySQL开发的。这些函数的注释很差，所以用doxygen运行时无法获得良好的结果。

谁来阅读文档？该文档将用于什么用途？这些是最重要的问题。例如，维护开发人员的文档将更多地关注结构，而与产品集成的开发人员的文档将更关注Web服务和数据库结构。

通常，只做所需的尽可能多的文档。许多组织都需要文档，因为有人坚持认为这是最佳做法，但是文档最终积聚了灰尘。

假定人们将实际使用该文档，请不要尝试将代码和数据库捕获到最小的级别。开发人员将查看代码的细节。相反，请专注于代码中不明显的细节，例如：

1. 产品满足的用例。考虑到产品的使用年限，这可能很困难，但是掌握产品的用途将为非技术读者和测试人员提供重要的背景信息。谁是市场上的竞争者（如果有）？产品范围内是否有其他物品？
2. 任何明确的非功能性要求。例如，产品被写成可以处理一定数量的产品吗？数据可以使用几岁？在哪里使用缓存？用户如何进行身份验证？访问控制如何工作？
3. 一个上下文图，显示与其他系统（例如数据库，身份验证源，备份，监视等）的交互。
4. （如果知道）风险以及如何减轻风险以及决策记录。回想起来，这可能很困难，但通常会有影响设计的关键决策。捕获您所知道的任何东西。
5. 通用设计模式或设计准则。例如，是否有访问数据库的标准方法？有编码或命名标准吗？
6. 关键代码路径，通常使用流程图或UML活动或序列图。项目中可能没有任何内容，但是这些通常是业务用户明确表达的内容。

即使没有所有这些信息，也请立即开始。您之后的开发人员将感谢您。

好的自动化单元测试或测试用例也可能是有用的文档，尽管对于技术含量较低的人员来说很难访问。

听起来您还需要进行文化上的更改以包括文档。从小规模开始，但理想情况下，除非至少具有最低限度的文档水平，否则不应“完成”该项目。这可能是最难的步骤，因为以上是您可以控制的事情。这是其他人必须购买的东西。但是，它也可能是最有意义的，特别是如果您做的下一个项目附带好的文档时，尤其如此。

过去，我与各种产品所有者或高级用户坐下来，审视了他们的主要用例，并通过一系列测试将其记录下来，从而解决了这种情况。将来开始进行更改时，可以将其用作系统的基准。这也可以帮助识别系统中没有所有者或用例的区域，并可能将其删除。

这完全取决于系统的大小。如果这是一个具有许多不同利益相关者的复杂系统，则可以创建一个高级组件图，详细说明存在哪些功能以及在哪里满足这些功能。这对于确定系统设计中的体系结构问题非常有帮助。

通常，我建议避免使用老式的文档，因为它会过时并且将来会误导开发人员。我总是尝试以测试的形式生成实时文档，这些文档将随着系统的发展而得到维护。

首先，您的目标受众是谁？未来的开发人员或其他商人？考虑到该问题的答案：

正如其他人所说，高层次的描述是您首先需要的。解释系统在更广泛的方案中试图做什么。解释其运行的内容，如何适应网络并与任何其他系统对话。然后，我将浏览每个屏幕，对其进行屏幕截图，并简要说明屏幕的功能以及它如何与系统的任何其他部分进行交互。如果是面向开发人员的，请保持对话性，就像您是第一次向开发人员解释该应用程序一样。毕竟，这就是文档的重点（我认为）。

任何复杂的处理或逻辑我都将使用状态图，数据流程图或序列图。绝对要做一个实体图，然后做一个数据库模式设计（两件事！）。也许是基本的类图，但要保持简单，只注意感兴趣的主要内容，开发人员可以通过查看代码来找出这些内容。

如果您在入门时遇到麻烦，只需假装在您旁边的房间里还有另一位开发人员，他不了解该系统的第一件事，我比较耐心，只需要了解它的要旨即可。然后开始解释，并写下你的意思:)

先前的建议都是好的建议，但是我也将考虑研究您的用户社区是否自己创建了任何临时文档。您的问题未指定是否已向用户发布过任何版本的“产品”（存在两年）。如果已在使用它，并且没有正式的文档，那么或者没有必要的文档，或者在某个地方的“非正式”文档可能是基本的，但也可能被用户视为必不可少的。尝试在网络上搜索可能代表关键API的工件，搜索论坛，询问高级用户以及搜索问题和答案站点。如果可能，请尝试编写满足技术或业务需求的文档。

问题是，您是要按现在还是应该对其进行记录？

我从您的问题中读到的是，您在考虑API文档而不是太多的用户文档，并且代码可能维护得不够好且含糊不清。

恐怕如果您现在进行文档编制，则一旦重构了代码，最终将浪费大部分工作。

我将采用以下方法：

• 通过遵循常见的最佳做法，使文档尽可能地不必要。选择您可以直观理解的好的类名，方法名，变量名
• 在有意义的地方分解巨大的怪物类和/或功能
• 使用PHPdoc注释-您可以使用工具来创建API文档
• 为此编写测试：这些测试将帮助您理解或定义代码应该做什么。

现在，您仍有未记录的内容：这可能是一般概念，体系结构等。为此，我实际上会编写文档-但只写真正有用和有用的内容。