We have a “web application” which has been developed over the past 7 months. The problem is, it was not really documented. The requirements consisted of a small bulleted list from the initial meeting 7 months ago (it’s more of a “goals” statement than software requirements). It has collected a number of features which stemmed from small verbal or chat discussions.
The developer is leaving very soon. He wrote the entire thing himself and he knows all of the quirks and underlying rules to each page, but nobody else really knows much more than the user interface side of it; which of course is the easy part, as it’s made to be intuitive to the user. But if someone needs to repair or add a feature to it, the entire thing is a black box. The code has some minimal comments, and of course the good thing about web applications is that the address bar points you in the right direction towards fixing a problem or upgrading a page.
But how should the developer go about documenting this web application? He is a bit lost as far as where to begin. As developers, how do you completely document your web applications for other developers, maintainers, and administrative-level users? What approach do you use, where do you start, what software do you use, do you have a template?
An idea of magnitude: it uses PHP, MySQL and jQuery. It has about 20-30 main (frontend) files, along with about 15 included files and a couple folders of some assets — so overall it’s a pretty small application. It interfaces with 7 MySQL tables, each one well-named, so I think the database end is pretty self-explanatory. There is a config.inc.php file with definitions of consts like the MySQL user details, some from/to emails, and URLs which PHP uses to insert into emails and pages (relative and absolute paths, basiecally). There is some AJAX via jQuery.
Please comment if there is any other information that would help you help me and I will be glad to edit it in.
The developer leaves on Friday. However he can dedicate most of his 24 remaining hours to this documentation task. So, yeah, things are bleak but 24 hours is quite a bit… right? :-\
I would start by listing the main features that the application currently implements (update the initial bullet points).
Then, for each bullet point, write down the main requirements associated with that bullet point.
For each requirement, write down:
This will give you something of a traceability hierarchy
Feature => Requirement => Implementation
It will also provide a good framework to jostle memories and write down gotcha’s.
Then, comment each php and inc page.
Start with a header that outlines the purpose and which requirement(s) from the previous list are satisfied (reverse traceability from code to requirement).
Go through each php/inc file and comment the major actions/decisions/loops indicating what they are trying to accomplish and any design considerations that are assumed (e.g. “input is assumed to have been validated in the previous step”).
When commenting the source code, you may want to use a tool such as PHPDoc so that you can generate documentation out of the comments.