Consultant in a firm that doesn't understand the tech! [closed]

Seems kind of odd that the staff don't know the platform you've been asked to re-write their work in. What happens after you leave? Who will support your work?

So you've got a complex system that doesn't have proper documentation, and you must re-create the system in a different platform. What I would do, in your position, is to identify the single person who must "sign off" on the new system. From there, do some reading on User Stories to identify how to break requirements down into bit-sized chunks that can be described in plain English. Their format is something like "As a USERROLE, in SYSTEM X, I want to ACCOMPLISH ACTION so that GOAL IS MET.

To further explain a User Story, you add in 'success criteria' in the format of "Given when CONDITION then OUTCOME" to explain what happens with different actions inside the parent User Story. This is a decent way of breaking out functionality into pieces that can be understood individually, and you can get help writing different Stories from different groups (just make sure the top-level person who signs off on the work stays the same).

So get all the old functionality of the system re-written as User Stories, then ask the project owner if there's any NEW functionality that they want in the Java version. Add stories to satisfy that, if there's any, and then start coding.

Basically, you need to be able to expose the staff programmers' unhelpfulness. Get the project owner to require that they provide you with the Success Criteria for some of the Stories, so that if they give you crappy input, you can just hold that up as your official requirements. Anything they leave out will be their fault, not yours.

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):

1. Create a set of code categories for business requirements (functional, bugs, validation, ui, etc.).
2. Create a set of categories for the screens (group them by similar functionality).
3. Create a list of all screens for the entire application and enumerate them within a spreadsheet.
4. Assign each screen a code category and a code type (e.g., business rule, system requirement, technical).
5. 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:

1. Developers make and test application changes in DEV (using a repository).
2. System tools automatically deploy regular builds into TEST.
3. 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.
4. 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.

They have no documentation and their code is so poor they've hired someone else to rewrite it in another language. Start gathering requirements from the source. You will find a lot of the features and functionality are no longer used or may not work properly. It's equally important to know what not to build.

Once you've found what the users need, determine what is already in the current application and what has to be built from scratch. The existing pieces is where you can look at the code and talk to the devs.

Anyone who proclaims they need everything has never bother to check. There is an arguement to never rewrite an application, but that assumes everything works the way users want it and that is not always true. They use it because there is no alternative. Give them a better alternative.

I would start by talking to you manager and accepting the responsibility for collecting the requirements and defining the specs. You will need to convince him of the need for these documents and what they will provide. I would probably find an example online. Then you take charge of assembling the requirements and the specifications for the system. Then meet with your manager again to go over the document. Once you have shown them the first document you may be able to get some assistance in creating the other 5. Other wise if it is effective then you will probably be responsible for gathering those requirements as well but at least someone will be doing it.