How to document an existing small web site (web application), inside and out?

Question

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? :-\

Answer 1

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:

• Anything quirky about that particular requirement
• Where in the code that requirement is implemented (which php, inc files, tables)

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.

Answer 2

One approach could be to arrange a series of hand over meetings. In these the developer would have to explain the code for each section.

He could write some notes in preparation for these, but having the other developers take minutes as well might help them understand the code. Also these meetings would be an opportunity to ask questions about aspects that aren't clear.

Don't try to do the whole site in one go. Break it down in two smaller chunks grouped somehow - by function or by area. This means that your other developers aren't bombarded with too much information in one go, the original developer can concentrate on one area at time and you have a chance to follow up after the meeting.

Even if nothing "sticks" straight away there will be some familiarity with the site when you revisit it later.

Another approach could be for the developer to give a series of short presentations on the site and how it was built. This might prompt him to remember why he took the approaches he did. This is invaluable when looking at code. If you know what problem it was trying to solve it's a lot easier to understand.