I have been involved in a project where the entire system was written in Oracle Forms, but without any documentation. The technology could have easily have been Perl. Here is the plan of attack for migrating the system to Oracle ADF (but could also just as easily be any other platform):
- Create a set of code categories for business requirements (functional, bugs, validation, ui, etc.).
- Create a set of categories for the screens (group them by similar functionality).
- Create a list of all screens for the entire application and enumerate them within a spreadsheet.
- Assign each screen a code category and a code type (e.g., business rule, system requirement, technical).
- Reverse engineer the code to extract the business requirements, crafting a one-sentence description of each requirement.
At this point you will have documented the business rules for the application. This alone will be gold for anyone who next has to maintain the system. Moreover, it will give you a chance to see what parts of the system have been duplicated. (In my case, we discovered that over 60% of the code base was duplicated.)
From here, you can sort through the business requirements with management. This might entail crafting user stories, for example. This will also reveal high-level duplicate functionality, and present opportunities to both simplify and enhance the system during migration. I have included a screen shot of the spreadsheet to show one way to go about tracking and documenting the requirements.
You might have to brush up on your Perl. ;-)
Once you have reverse-engineered the project, you can employ a suite of tools to help you out with the software development life-cycle. (We're using JIRA, but there are many other software suites that would work.) You might have some fighting to do, but once you have the requirements down, you'll want to move to the following environments:
- Create a documentation environment (e.g., a wiki).
- Create a development (DEV) environment. Web servers, database servers, source repository, etc.
- Create a test (TEST) environment that mirrors development.
- Create a pre-production (PREPROD) environment that exactly mirrors production, and can act as a fail-over for the production system.
- Create a production (PROD) environment.
Think about using a community-oriented service to tackle the requirement of end-user documentation. An excellent software package similar to the StackExchange suite is OSQA. Let the users build the help system (it's quite a clever strategy).
The SDLC becomes:
- Developers make and test application changes in DEV (using a repository).
- System tools automatically deploy regular builds into TEST.
- Once testers are satisfied with the application, the application is deployed into PREPROD. This allows the deployment process to be tested as well. More testing happens in PREPROD.
- Once testers are satisfied with PREPROD, the application is finally rolled into PROD.
I find this to be a highly-organized approach that works well with different development methodologies. The first pass, which I have described here, should be considered a "broad brushstroke" -- you don't want to get too detailed (bogged down) with technical minutia at this point. (User interface requirements, for example, are captured by each screen. As long as you have the screens enumerated, you needn't iterate every single input field -- just link to a screen shot or working URL.)
Lastly, to review the source code, we auto-generated a series of web pages (one web page per functional "screen"). This worked well because the PL/SQL code could be split into separate files, and automatically converted to HTML with syntax highlighting. With Perl, this might not work as well for you. The idea, though, is that you can create anchor links within the spreadsheet that point back to the section of code that enforces the business requirement. (As an aside, this would also allow multiple developers to reverse-engineer the system requirements in parallel because each developer can tackle different screens simultaneously.)
An example source code snippet (the + is an anchor link):
You could recommend hiring a couple of Perl gurus to help with the analysis task.
I don't think it's very productive to point out that other people are doing "crappy work"; rather, you should be looking to improve the product and give people an opportunity to help with this goal (and perhaps learn how to improve their skills in the process). That is, you don't know what the other developers know, nor were you there when they developed the system. This approach makes the entire process open and highly visible whereby everyone can contribute.
Honestly, managers will see for themselves who is genuinely helpful and who wants to improve.