PROJECT DOCUMENTATION WITH ENTERPRISE ARCHITECT

Transcription

1 PROJECT DOCUMENTATION WITH ENTERPRISE ARCHITECT How to organize project documentation with Enterprise Architect. By Amir Firdus ( March 2010 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 1/5

2 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 2/5

3 Design Home Page Sample project directory structure is shown in the table below. Directory docs 1-analysis 2-design 3-implementation 4-deployment 5-resources ea html Description Contains various documents. Can be organized in number of ways. In this case sub-directories match project phases. In addition it has a resources sub-directory to put images and configuration files. Contains Enterprise Architect project file. Directory where documentation in HTML format is generated. 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 3/5

4 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. 4/5

5 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 Download Sample project documentation is available for download at 5/5