They meant well. They created their design documents before coding to make sure their strategy was spelled out thoroughly. They had a database diagram, a UML model, and more. They patted themselves on the back, and got started on development. Things went great until...

"The requirements changed"

The notion of trying to create perfect requirements and design documents up front is old fashioned. It's generally considered inevitable these days that requirements will change during the development cycle for any significantly complex project.

When this happens, they open up Access (or SQL Server Enterprise Manager, or whatever database management tool they have) and make the necessary database changes and get on with development. They should update the database diagram and UML model to reflect the change, but all too often that just doesn't happen. Maybe they meant to, but forgot. Or maybe they had a tight deadline and didn't have time to tinker with such niceties. The documentation falls out of date, and gradually turns into something near worthless.

It's a story that's been repeated over and over again throughout development history, but it doesn't have to be that way. Using Visio, a tool you likely already have hanging around your company, you can keep your documentation up to date with little to no effort. How can this be done? Documentation that forward and reverse engineers modifications can keep itself up to date.

Visio for Enterprise Architects comes free with Visual Studio Enterprise Architect edition. It has extra tools that the standard edition of Visio does not have. These tools enable forward and reverse engineering of databases and code. Visio can actually generate skeleton C# or VB.NET code based on the documentation created with it. Even applictions with unique structures can be generated because the code templates Visio uses can be customized to fit almost any need. For a large project, the boilerplate code it generates can save weeks of tedious coding, allowing you to move onto the more interesting business logic code.

Picture this: The design requirements change in the middle of development (as usual) and these changes require a modification to the structure of the database. Open the database diagram, add the new fields, and command Visio to forward engineer the changes. From within a single application, the documentation and database have both undergone changes and stayed in sync with each other. This is clearly a more agile way of doing development.

If you haven't used Visio lately, you might not know how much its database design capabilities have expanded over the last few versions. It's a thoroughly slick tool that can handle almost all the needs of a serious database design architect. But no tool is perfect. If you run into a database change that Visio can't handle for some reason, go ahead and make the change through the database front end and then have Visio reverse engineer the change.

The (Distant?) Future: Visual Studio 2005 Team System You may have heard about Visual Studio 2005 Team System (codename: WhiteHorse) which is currently in development at Microsoft. The marketing folks say it will have all kinds of great design and collaboration tools built into it. While the hype around it is certainly tantelizing, the realist in me can't help but point out it's currently little more than vaporware. As of this writing, we're still waiting on what feels like a very delayed beta 2. As great as version 1.0 of Team System may or may not actually end up being, if you're building an app now you need a solution now. Visio is one of the best design tools currently available for companies with limited budgets, especially considering they've likely already paid for it.

Automated Database Engineering

To reverse engineer a database, open Visio for Enterprise Architects and create a new Database Model Diagram. (Don't confuse this with the ER Source Model – these two templates look similar but the ER Source Model provides less functionality.)

Then, from the Database dropdown menu, choose Reverse Engineer. Follow the steps in the wizard to connect to the database. The wizard steps vary somewhat depending on what kind of database is chosen. Visio provides database drivers for SQL Server, Access, Oracle, Sybase, Informix, DB2, and more. In most cases an option will be provided options to select which kinds of database items are to be reverse engineered, such as specific tables, views, keys, etc.

The option will be presented to allow Visio to arrange the tables automatically, and for smaller databases this works great. For larger databases it usually works out better to handle the arrangement manually.

At this point the database diagram has been successfully created. When changes are made to it, the physical database can be automatically updated by selecting Update from the Database dropdown menu.

Creating a brand new database is simple and easy once you've done a little tinkering to get a feel for it. Just drag and drop an "entity" (otherwise known as a table) onto the diagram start adding columns. Drag a "relationship" line onto the diagram and connect each end to a table. After a new database model diagram is ready to be turned into a real database, simply select Generate from the Database dropdown menu.

Automated UML Diagrams

Databases aren't all that useful without some kind of user interface with which users can interact with the data. Software fills the gap, and these days the planning and complexity of involved in software development is often managed by Unified Modeling Language (UML.)

One of the nice things about UML Model Diagrams in Visio is that you don't actually need to know anything about UML. Just drag and drop your objects and their relationships in a manner that very similar to creating database diagrams. Underlying it all is UML, a fact which you don't have to care about. What's more important is that your software design is laid out in a very clear and concise way so that managers and fellow developers can use it to wrap their heads around the software design.

Once a class has been dragged onto the Visio diagram, double click it to open up the properties dialog box. This provides ways to configure all members of the class, including methods, events and parameters, both public and private.

When the diagram is complete, Visio will generate the skeleton code for all the classes in your choice of C#, C++ or VB.NET. To do this, select Code | Generate from the UML dropdown menu. The code it generates by default is adequate in many cases, but the templates Visio uses can be customized almost infinitely by choosing Code | Preferences from the UML dropdown menu.

Visio for Enterprise Architects also works well for reverse engineering existing code. Assuming it's installed on your development machine, there should be a Visio UML toolbar available (try right clicking on the Visual Studio Toolbar to find it.) This toolbar contains a single button that kicks off the simple process of reverse engineering whatever project is currently loaded in Visual Studio.NET

Impress Customers with Reams of Documentation

Having accurate and up to date design diagrams is more than a lot of development teams can claim, and that should go a long way toward convincing customers that you're part of a truly professional development team. But what if you could also deliver to your customers (or your boss) a stack of detailed paperwork that accurately described the design of the application? You don't have to confess that all that documentation only took you seconds to generate using Visio's built-in reporting capabilities. Simply select Report from the UML or Database dropdown menu. The resulting dialog box is full of many tabs that allow the configuration of many different kinds of reports. There are options for specifying the level of detail for each of the reports, as well as options for configuring headers and footers to match your company's standards. The resulting reports can be previewed and exported to Rich Text Format (.rtf) which is compatible with all modern word processors.

At this point you should have a good idea about how to embark on the process of creating and managing documentation for your projects in a reasonably simple and painless way. Visio has come a long way in the last few versions, and it's one of the most user friendly design tools you're likely to encounter. No design tool is perfect, but it's hard to match the power and wide compatibility of Visio.

Steve Orr is a developer and author, and can be found at SteveOrr.net.