an entry from

Piotr's R&D blog

Here's a project proposal for a software documentation tool tentatively called "The Morning After". There are two assumptions you have to buy into: first, that well-done UML diagrams provide useful documentation for a system, and second, that typically developers will draw such diagrams only under duress. Still with me?

Adoption Issues

Current UML editors suffer from an adoption problem. Unless their use is mandated, few developers will choose to use these tools to do their design. I believe this is because they are too unwieldy for quick sketching¹ and don't provide sufficient extra value to offset this deficit. Most agile processes recommend the use of pencil and paper (or whiteboards) for drawing informal diagrams, an approach that has met with some success. Unfortunately, the diagrams drawn this way are not always captured, and almost never updated as the code base evolves. Consequently, their use for documentation purposes is dangerous: an incorrect model is worse than no model at all.

There are two typical responses when people realize that things aren't working out, but still want UML diagrams for whatever reason.

1. The big-bang approach says that you should do whatever you need to do to get your system working, then document all the code at the end, possibly with the assistance of some reverse-engineering tools. Though popular with procrastinating SEng students, it requires a lot of discipline to get right since documentation is not an inherently interesting activity for developers, and piling it on when they are burnt out at the end of a development cycle is often ineffective. Even with reverse-engineering, there's just too much to look through and correct all at once.
2. The in-sync approach attacks the problems with tools, integrating UML diagrams tightly with the code, making sure that they always match (e.g. Together or EclipseUML). This is tricky to do right and requires that all developers be using the same development platform. Furthermore, in my experience, drawings diagrams and writing code requires two different mindsets; I don't want to be distracted with maintaining a diagram when I'm trying to solve a tricky low-level problem, or be distracted with generating correct code when trying to work out high-level design issues.

A Happy Medium

Here's a third approach, a scenario that I think hasn't been tried before. The developer sketches on paper and writes code all day, checking it in when it's stable. Overnight, our system analyzes the additions and changes, then reverse-engineers appropriate UML diagrams highlighting any changed areas (a visual diff). The morning after his coding binge, the developer comes in and checks his mail over coffee. The diagrams are waiting in his inbox, embedded with SVG and editable in-place. The developer looks over diagrams (perhaps comparing them to his sketches), makes some corrections, and puts the revisions back into the system to be used as the base for the next iteration of diagrams.

I think this system would combine many advantages:

• Editing a diagram requires much less effort than creating one from scratch. Furthermore, the diagrams are built iteratively, avoiding the big-bang effect.
• The editing process fits the developer's workflow and does not require him to install and (remember to) run extra software. Diagram reviews can be postponed by leaving them in the inbox, or the message dragged into a standard to-do list. Diagrams can also be easily annotated and forwarded between team members.
• The system provides some extra value to the developer, since reviewing the reverse-engineered diagrams may allow him to spot high-level bugs (e.g. introducing an undesirable dependency between packages, creating a reference cycle, etc.). The diagrams can also be automatically integrated into a project's on-line documentation (such as Javadocs), giving the team models that they can be confident are not stale.
• The application architect can keep track of the system's evolution in real-time, and step in early when reality starts to deviate from his design (possibly by modifying the design).

Getting There

The project involves many challenges:

• Creating an incremental reverse-engineering algorithm that will preserve the users' model and diagram edits as much as possible even though it's only fed coarse-grained difference information rather than fine-grained edits.
• A diagram selection algorithm that will heuristically decide which diagrams are likely to be most useful, since the system can't present more than a handful of diagrams to a developer every morning.
• A visual differencing algorithm to highlight the changes in the diagrams.
• A (simple) UML editor written in SVG, and a two-way converter between UML models and SVG diagrams.

Footnotes

¹ New user interfaces based on tablets or electronic whiteboards might solve this problem in the future.