What kind of documentation and other artifacts would you expect to get in case of taking over existing Java webapp (probably it uses JBoss Seam framework) made in-house?

I would expect to get:

  • Source code in form ready to open in specified IDE.
  • All external elements (i.e. DB schema as SQL scripts, installation scripts).
  • Configuration files (both for devel, testing and production environments).
  • All external libraries needed by project.
  • All external tools used in project or at least their description (i.e. make program, version control software).
  • Detailed info about:

    • How to compile project (IDE, libraries, their versions, compilers, OS),
    • How to setup development environment (database version, OS, DB schema),
    • How to install and run application -- server specification (OS, database, versions, minimal hardware, configuration both app and DB),

Probably it would be also nice to have:

  • Archive of the whole version control system (to make possible checking changes from the past).
  • UML diagrams or other form of big picture of application design.
  • DB schema.

What I miss?

Some background details

Friend works as a lawyer for a company which needs legal agreements with people who develop applications for them. Just in case something goes wrong.

In general -- the company wants to have source code deposited somewhere. But source code is not enough to maintain or even compile and run webapp, so they also needsome documentation which helps maintain the app.

I've never taken someone else's project in a similar case (no access to previous developers), and I am not Java developer, so I expect there are a lot of things to miss.

More details added after a few answers

The bosses of company (named it A, small corporation), which ordered and uses the app and company (named it B, a few people) which writes the app, are friends.

Development is in-house. No formal spec, no written specification. All features are discussed over mail or on meetings.

Everything, including hosting the app, is managed by B.

Friend (who is also one of heavy users of the app -- let's say she is product owner) doesn't trust developers from B at all.

Friend also doesn't believe in B competencies (believe me -- she should not).

So to protect A business friend wants written legal agreement with B in case B would go away with A data and app...

As MSalters wrote -- don't laugh -- it happens :(.

A already made B to make and provides backups.

  • 1
    All of the above. If any of the above cannot be provided an explaination should be given. This should be noted on the contract. Unless the company in question needs the source code, then there is no reason for the source, sounds like they don't do development work in house. – Ramhound Sep 16 '11 at 10:56

Source code in form ready to open in specified IDE

above, though nice to have, feels rather slippery - leaving too much room to fuss over IDE version, plugins, configuration. "oh by the way this will work only if you install and enable Habracadabra plugin v 6.6.6. And, hey, just in case if you don't know, this version of Habracadabra works only with Netclipse 3.4.5"

  • When taking over I'd prefer to insist on having source code ready to build from command line

  • Also, in case if "they" use issue tracker for the project, I would do my best to squeeze all the data about these issues somehow (all issues in tracker, no matter fixed or not) - either by completely taking over that issue tracker with or by getting a read-only access to it or at least by getting a "snapshot" of it by whatever means.
    Information stored in an issue tracker might be a great help for maintainer

update Can't tell if this qualifies as an artifact but given details provided later, I'd consider some sort of service-level agreement to somehow "bind" their developers to answering questions about the application.

  • "For first 3 (4,5) months mean time to answer within 8 hours, assuming 100 or less questions a week. For next 3-6 months mean time to answer within 24 hours, assuming 10 or less questions a week..."
  • As far as I known there is no issue tracker. Everything is discussed over mail or in meetings :(. – Grzegorz Gierlik Sep 16 '11 at 14:00
  • 1
    @Grzegorz try to get their mail archives, then :) And, well, be prepared to some tough time. Lack of tracker is a bad sign – gnat Sep 16 '11 at 14:14

I have to manage more than a few outsourced development projects. One trick to make sure you get a buildable, runnable project is to make sure that you own and host the source control server and build/qa environments. By definition you'll have a buildable, runnable copy of the project with full history.

  • Unfortunetly is impossible -- they outsourced everything other then core activity. – Grzegorz Gierlik Sep 16 '11 at 13:57
  • Doesn't mean you can control the core of the infrastructure -- make them commit to your github or bitbucket repo. And run stuff on a CI server that you own. – Wyatt Barnett Sep 19 '11 at 11:38

The following points might help too:

  • (JUnit) Tests
  • JavaDoc (automatically generated from the source code, might give a good clue about the quality)

But in general, a knowledge transfer between one of the developers and the new maintainers might be "a good thing" (tm).

Seeing as the webapp was ordered by the company, the company has decent docs/specs about what they wanted to have?

  • I don't believe they use automatic tests or JavaDoc. Also seems to be impossible to transfer knowledge. Agreement is for case of hostile divorce. – Grzegorz Gierlik Sep 16 '11 at 13:59

"docs/specs" (mentioned by Turbo) is indeed a very good point. You might want to add in the original requirements as well, and the current issue tracker database. When those are managed by email (don't laugh, it happens) you'd want those emails instead, and you'd charge the client for entering them into a proper issue tracker.


All the documents are important but I have a trick which works pretty well. Many developers just change the code and sometimes the static architecture. They are so involve in the job that usually just write a quick javadoc which makes it almost impossible to understand what has been done.

My trick is to ask the developer to reverse the package into a class diagrams each time he/she add/change something in the architecture which is used by other objects. I don't need a lot just a visual class diagram which is automatically made by the tools and a graphical note on class and on methods. If more is needed then I ask a detailed note directly in the UML object at model level. It means that if somebody else want to add new code to an existing code he/she will be able to open the package, see the structure and business methods in the IDE outline and navigate in the code with documentation available as class diagrams using the mouse to click on each class to have this class specific documentation. I mean that he/she can navigate in the code with the code, the outline, read the javadoc and then navigate in the object architecture using the diagrams and clicking on the class inside the diagram which will open a description menu in which information has been saved.

The result is impressive because class diagrams are really easy to be created, documentation is just two minutes to be written and new developer can start to code almost immediately in the project without breaking existing code. This UML trick only works with java/jee projects for the class diagram. As soon as you introduce more than one diagram then the project get ctoo heavy for developers who will sooner or later refuse or forget to create diagrams. Class diagrams having the same object structure as code is easy, fast to create and read and really improve productivity. I have forgotten to say that you need to able to merge existing code with new model to have a full cycle. I would therefore recommend live code and model synchronization when the UML class diagram is open but you should also be able to close your diagrams to focus on code and just open it when you need it. This is the merge option.

My trick only work at code level with java annotations which are also reversed and manage by the tool. I usually use JBoss or Weblogic with Oracle or MySQL databases.

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