Overview

It is not an easy step to go from reading about UML and UML tools to handling a real project documentation. In reality project documentation consists of documents in different formats: text, diagrams, presentations and lately even media files. We need a way to bind them all together. Enterprise Architect offers a solution with its common elements: Boundary, Text and Hyperlink. They are not talked much about but they are the key to the complete documentation set.

Sample Project

For illustration, I have created the Sample project. Its structure follows well defined project phases. Here they are, both in more traditional engineering and Unified Process terms:

• analysis (inception)
• design (elaboration)
• implementation (construction)
• deployment (transition)

This is how the Project View for the Sample project looks like:

Enterprise Architect Project View

By using common elements we can create practical and eye pleasing documentation sets. From the documentation point of view, the Hyperlink element is the most important one. With Hyperlink element, we can embed links to the documents external to Enterprise Architect directly into the diagram.

Here are the instructions:

• To create a page, use an empty diagram (e.g. Project Home Page)
• To style and organize the page, use Boundary element (e.g. yellow rectangle used for the page header)
• To add logos and other images, use Boundary element and set the background image (e.g. Firdus Software Consulting logo)
• To add labels and text, use Text element (e.g. Team label)
• To create links to external documents, use Hyperlink element (e.g. design.txt link)
• To create diagram links, use Hyperlink element (e.g Analysis Home link)

Once the page layout is created make elements that are not expected to change often non selectable, so that they do not get in the way.

This is how the Project and Design Home pages look like.

Project Home Page

Design Home Page

Sample project directory structure is shown in the table below.

All the effort put in the project documentation would bring little value if the knowledge stored within is not shared. The first step in this direction is to distribute the project documentation. For the more technical audience Enterprise Architect itself or Enterprise Architect Viewer will work just fine. For the broader audience, documentation in the HTML format works better. In this case, Enterprise Architect exports all the diagrams, linked documents and the navigation code in an export directory. To start using the project documentation we just need to open “index.htm” file from the export directory in one of the web browsers and start navigating using the available links, as shown on the image below.

Project Home Page in HTML Format

What Next

Learn tools. Tools can help a lot. Still, it takes experience and knowledge to do it right. Here are few experiences that could come handy.

The most important thing is to adjust documentation to the project at hand, not the other way around.

Keep the mindset agile. Only the mindset can be agile, procedures are not. Trying to define an “agile procedure” is kind of a contradiction.

The variations from one project to another are the reality. They are driven by many factors: project size and scope, risk handling strategy, high technology and tools turnaround, activity management strategy and many more. Be ready to adjust and fine tune things on the fly.

Iterations are one of the key factors in managing the project scope and reducing the risk. With the iterative approach possible issues are discovered sooner giving us a longer reaction time. Nevertheless, iterations introduce an overhead, so be careful not to overdo it.

Avoid using templates and wizards to generate models just to leave most of them blank. Much rather, create one at the time as needed.

When working in the development trenches, it is better to document than not to. Use UML as much as possible. Document the rest in any meaningful format.

Enterprise Architect can help with all of these in a cost effective way.

Conclusion

Enterprise Architect can be used to organize complete project documentation. Its common elements can be used to bind documents in different formats together. Enterprise Architect export feature can be used to generate a documentation package that is practical to use and easy to distribute.

References

http://www.sparxsystems.com

http://www.ambysoft.com/unifiedprocess/aup11/html/phases.html

Download

Sample project documentation is available for download.