Ric*_*ket 7 php documentation web-applications
我们有一个过去7个月开发的"网络应用程序".问题是,它没有真正记录.这些要求包括7个月前初次会议的一个小项目符号列表(它更多的是"目标"声明,而不是软件要求).它收集了许多源于小型口头或聊天讨论的功能.
开发人员很快就要离开了.他自己写了整个事情,他知道每个页面的所有怪癖和基本规则,但没有其他人真正了解它的用户界面; 这当然是最简单的部分,因为它对用户来说是直观的.但是,如果有人需要修复或添加一个功能,整个事情就是一个黑盒子.代码有一些最小的注释,当然,Web应用程序的好处是地址栏指向正确的方向来解决问题或升级页面.
但是开发人员应该如何记录这个Web应用程序呢？他有点迷失到哪里开始.作为开发人员,您如何为其他开发人员,维护人员和管理级用户完整地记录您的Web应用程序？你使用什么方法,从哪里开始,你使用什么软件,你有模板吗？
一个大小的想法:它使用PHP,MySQL和jQuery.它有大约20-30个主要(前端)文件,以及大约15个包含的文件和一些资产的几个文件夹 - 所以总体来说它是一个非常小的应用程序.它与7个MySQL表接口,每个表都有很好的名称,所以我认为数据库端是非常明显的.有一个config.inc.php文件,其中包含MySQL用户详细信息,一些来自/到电子邮件以及PHP用于插入电子邮件和页面(相对和绝对路径,基本上)的URL等定义.通过jQuery有一些AJAX.
请评论是否有任何其他信息可以帮助您,我将很乐意编辑它.
开发商周五离开.但是,他可以将剩余24小时的大部分时间用于此文档任务.所以,是的,事情是惨淡的,但24小时是相当多的......对吗？: - \
我将首先列出应用程序当前实现的主要功能（更新初始要点）。
然后，对于每个要点，写下与该要点相关的主要要求。
对于每项要求，写下：
这将为您提供可追溯性层次结构
功能 => 要求 => 实施
它还将提供一个良好的框架来整理记忆并写下陷阱。
然后，注释每个 php 和 inc 页面。
从概述目的以及满足先前列表中的哪些要求（从代码到要求的反向可追溯性）的标题开始。
浏览每个 php/inc 文件并注释主要操作/决策/循环，指示它们试图完成的任务以及假设的任何设计注意事项（例如“假设输入已在上一步中得到验证”）。
在注释源代码时，您可能需要使用PHPDoc等工具，以便可以根据注释生成文档。
一种方法可能是安排一系列移交会议。在这些中，开发人员必须解释每个部分的代码。
他可以写一些笔记来准备这些，但让其他开发人员也花几分钟时间可能会帮助他们理解代码。这些会议也将是一个就不清楚的方面提出问题的机会。
不要试图一次性完成整个网站。将其分解为更小的块，并按功能或区域以某种方式分组。这意味着您的其他开发人员不会一次性受到太多信息的轰炸，原始开发人员可以一次专注于一个领域，并且您有机会在会议后进行跟进。
即使没有什么东西能立即“粘住”，当您稍后重新访问该网站时，也会有一些文档和对该网站的一些熟悉。
另一种方法是开发人员就网站及其构建方式进行一系列简短的演示。这可能会促使他记住为什么他采取了这些方法。在查看代码时，这是无价的。如果你知道它试图解决什么问题，那就更容易理解了。