Most companies with a significant investment in Microsoft .NET development technologies have also invested in Microsoft productivity tools. Given the right process, configuration, and discipline, companies can combine their development environment and productivity tools to create a usable system design and maintenance configuration. Let’s review the documentation process and examine which products and tools to include in your system design toolbox.

Documentation process
Even though every company agrees they should have a software development life cycle (SDLC), no two companies agree totally on which phases and work products comprise one. Before creating your own software design methodology and choosing which tools you’ll use to implement it, you must first define your design and documentation process. Part of the definition should include a set of documents created and maintained for each project. At a minimum, you should create the following documents (or other documents that include all of these components).

Business requirements
The business requirements document should summarize the reasons for developing the system, the expected overall system cost, and the benefits to be realized. It should list the expected utilization and performance metrics, (e.g., how many and what type of users will use the system and what kinds of response times will the system be designed to deliver). The business requirements document will be used to guide all future phases of system design. Any changes to this document must reflect the realities of design and development and need to be approved before design or development continues.

Process diagrams and use cases
Once the business requirements have been defined, the architect must turn his or her attention to documenting how information flows between key actors in the system. Defining actors and processes is the key to creating use cases, which define each major system function in terms of the people or systems participating in the system. Taken together, the process diagrams and use case documents provide the information that bridges the business requirements with the top level of technical implementation. As such, the documents should be easily understood and editable by the customer (or business advocate) and the system architect responsible for creating detailed technical documents.

Modeling documents
The system architect should use the process diagrams and use case models as source documents to create class and database models. The class models represent the system as a set of logical classes that implement the major functions of the system as defined in the use cases. The database model will provide the physical design of the database required to store transient process state information, persistent system outputs, and historical transaction data.

Three major tools for system documentation
Of course, you’ll never get all the requirements or design documents completed perfectly from the start. It is important to use tools that allow you to make and publish design changes as they occur during development. To have access to all the tools you need to create a design environment, your developers should have, at a minimum, Microsoft Office Professional and Microsoft Visual Studio .NET Enterprise Developer. All your architects must have the same version of Office and should use Microsoft Visual Studio .NET Enterprise Architect. This will provide the architects a license to use Microsoft Visio for Enterprise Architects.

For your design environment, the key tools are Microsoft Word, Microsoft Visio, and SharePoint Team Services (STS). Word has some excellent team collaboration tools. Selecting track changes from the tools menu allows multiple people to edit a document and have all of their changes recorded in the document. Instead of making changes in the document directly, editors (i.e., business advocates, architects, or developers) can add comments to the document. They can send copies of the document to reviewers. And once it’s returned, they can merge all changes into the original document, decide which changes to accept or reject, and make other changes based on the comments.

The version of Visio included with the Enterprise Architect version of Visual Studio .NET includes templates for creating use cases, class models, and database diagrams. You can even generate function templates from the class models and database schema for SQL Server and other ODBC-compliant databases using the database diagram tools. In fact, for existing systems, you can reverse engineer VB code into class models and databases into database diagrams. Visio doesn’t track changes from multiple users as Word does, but it is important to get feedback on the design. To allow comments on class models and diagrams, I recommend having architects export their models and diagrams to JPEG files and then paste the files in a Word document. This allows you not only to print or view the diagrams, but also to use Word’s Track Changes features.

Once the documents have been created, place them somewhere that multiple users can view and comment on them. Microsoft ships a simple collaboration server with every copy of Office 2000, Office XP Professional, and with Microsoft FrontPage 2000 and higher. This tool, STS, is used to create a Web-based portal that serves as a repository for key design documents.

STS provides a simple mechanism to upload and download documents using either a Web browser or the file open/save mechanisms in Word or Visio. Moreover, portal users can subscribe to either the site or individual document to receive notifications any time STS detects a change in the document. In fact, if you use either Word or Internet Explorer 5.0 and higher to view the Word documents, you can make inline comments and changes without having to download them first. Many architects prefer to use Visual SourceSafe to store their system documents because it has check in/out capabilities. But its lack of notification capabilities makes it less of an ideal choice.

Making it all work
System architects ultimately decide on the set of tools used to manage the SDLC. Whether you spend $5,000 per seat for a full blown Rational environment or choose to create a design environment from existing licensed tools, you will not succeed without following the discipline of updating documents when the design changes based on issues that arise during development. But combining a well designed collaboration environment with a documented and enforced development methodology allows you to deliver applications that meet the business requirements on time and within the prescribed budget.