Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I got the job as a Consultant in a firm that has 3 other programmers. My job is to rewrite all the old system in Java, Spring etc but the staff programmers only know perl and the manager does not know any programming.

I am trying to get them to understand that I have 6 projects to rewrite here but no one has design docs or spec. the staff programmers never had to write any documents. Plus I cant get the manager to understand the new java tech stuff.. he keeps asking some of the staff for views on things but the staff don't know it or understand it.

Where do I go from here to make the manager understand that the staff programmers or someone has to write a design document so I know what to build. or if I have to write the documents how do I get the information?

share|improve this question

closed as off topic by TMN, Walter, Robert Harvey, gnat, ChrisF Nov 8 '12 at 23:01

Questions on Programmers Stack Exchange are expected to relate to software development within the scope defined by the community. Consider editing the question or leaving comments for improvement if you believe the question can be reworded to fit within the scope. Read more about reopening questions here.If this question can be reworded to fit the rules in the help center, please edit the question.

Ask more questions. I've been in your situation and all you can really do is continue to ask questions until you know enough to write the design documents yourself if they refuse to write them. – James P. Wright Nov 6 '12 at 18:12
thanks. I been trying but I cant get them to give me information. everyone is telling me... I dont know what the perl code does etc etc – techsjs2012 Nov 6 '12 at 18:19
Take a step back and stop asking what the code does but how its used. Learn how they interact with it and what they expect the output to be may be a better approach than untangling a web of perl without documentation. – Rig Nov 6 '12 at 19:02

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.

share|improve this answer
Where are the business analysts when you need them? – kush Nov 6 '12 at 22:16

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. ;-)

Example Requirements Spreadsheet

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

Source Code Snippet

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.