This part of the posting above was somehow misleading. I will fix it soon.

You should use UML diagrams to communicate some of the aspects of your design. UML is a good language for describing the structure of the code.

At the same time, you should use it wisely and you cannot settle for plain diagrams. Here’s what you should do:

1. Create a set of UML diagrams. Create them selectively: they should not contain each and every little detail. Each should describe an aspect of the product. Some should describe how aspects interact. This resolution will help the developer find his way in the code.

2. In any case, do NOT reverse eng. the code. This will create a cluttered diagram with a lot of information that will cuase a new developer to get lost in it.

3. Diagrams are not enough. Use plain English descriptions as well. There are many aspects which cannot be described using UML (at least not conveniently), and which are extremely improtant to future development. Implicit assumptions and behavioral contracts are great examples. They are part of the design, and when they break you end up with hard-to-solve bugs. Listing assumptions and contracts clearly will help developers to maintain them.

Another issue, which is often missing from UML diagrams, is the role of each entity: it’s scope of responsibility. Again, this is a great guide to developers, and it is also improtant to maintain a stable design.

4. Provide a plain English overview of the product’s design. It should include the rationale for the major design decisions. It should help developers know how to approach all the information listed above.

I hope this makes things clearer. Please let me know if it doesn’t.

Lidor

I hope you will succeed!

You might want to try creating the change yourself. Write clear and concise documentation to help the maintenance people do their work more effectively. Even if they don’t require it. Soon, they will learn to appreciate it. They might even get used to it and demand it.

Lidor