Get documents about "PROJECT MANAGEMENT WITH DESIGNER
Document Sample
PROJECT MANAGEMENT WITH DESIGNER
Marc de Oliveira, NNE
Introduction
The first time I learned about Oracle*CASE (as Designer was called originally), the vision was that this tool would cover the
entire development lifecycle from the early strategy phase through analysis, design, development, and test to implementation
and maintenance, including system documentation and user help.
At that time—1989—the tool was not ready to solve all of these tasks but its vision was good, and the principles that it was
built upon seemed well-planned and durable. It was easy to imagine how the product would evolve in the future.
Literature
It was also in 1989 that Richard Barker wrote the book CASE*Method Tasks & Deliverables, where he described a very
detailed project management method that followed the exact model of Oracle*CASE.
Later Paul Dorsey and Peter Koletzke wrote Designer Handbook, which is a good guide for learning how to use Designer but
also (especially in the second edition from 1999) how to manage development projects with Designer.
I should also mention Kent Graziano and Mark A. Kramm’s book, Oracle Designer: A Template for Developing An Enterprise
Standards Document, where naming standards, template standards, document standards, etc. are suggested. The book
contains a CD-ROM with all their examples so that you only need to add your company’s name to make them your business
standards (or you could actually change them to fit your organization’s needs and culture).
Principle No. 1
A common thing about these books is that they all try to cover every detail and possible deviation of any development project
imaginable. This makes their ideas quite complex to work with, and that is the way it should be. It is much easier to cut away
what you don’t need in a specific situation than to add missing elements.
There is no doubt that I would follow all of their advice to the last detail if I was to build a space rocket using Designer, but my
reality is usually simpler than that. My projects are often less than one man-year, and my customers are not used to evaluating
large volumes of system documentation before using new applications.
If a project management method is too complex, it ends up not being used at all. The result is that systems are developed
without any method.
That is the reason we took the material from the previously mentioned authors and filtered it through the following principle:
”What can we get for free now that we already use Designer as the development tool for our projects?”
- Principle No. 1
Instead of starting with requirements about traditional documentation and asking ourselves how we could get that out of
Designer, we turned the task upside down and asked how the documentation that is already placed in the Designer Repository
could be made available in a way that would be understandable for those without knowledge of Designer.
That would give us some level of documentation that would not cost our development projects anything to produce. If we still
needed more important documentation, we would have to add it later. And as is shown in this article, we did manage to
produce quite a bit of documentation from the Designer Repository.
The Development Model
By looking at the Designer Repository, we found the following project phases appropriate to use as our framework. These are
the phases Designer will easily support.
VISION STRATEGY
This is the initial phase where the idea of building an application comes to life. The most important document of the initial
phase is the vision document that describes the overall purpose and general functionality of the application in a way that would
make it possible for a manager to approve and start the actual development project.
Other documents of the vision/strategy phase are process diagrams, simple ER diagrams (without attributes), and high-level
function hierarchies.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
ANALYSIS
In the analysis phase the application is defined in detail. As with the vision/strategy phase the customer is very involved in the
analysis phase. The most important document of the analysis phase is the requirements document that describes in detail
what problems the application must solve.
To achieve this, it can be necessary to define some central business terms and describe the entities of the ER diagram and
the function hierarchy in detail. In this phase it is also important to get an idea of the resource needs of the project.
DESIGN
The solution is described in this phase. That means that you find out how you are going to implement each requirement of the
application. The most important documents of the design phase are the design document that describes how each
requirement will be implemented and the test plan that will assure that the requirements are actually being fulfilled by the
system.
IMPLEMENTATION
In this phase the application system is implemented as described in the design document. The most important documents of
this phase are the system document that describes how the completed system is built and the user guides that explain how to
use the system.
In this phase the unit test is performed, but we do not feel that it is very important to document it as it is not directly relevant to
the customer (this does not mean that the unit test should not be done!).
TEST AND DELIVERY
In this phase the official application test is performed and the application system is approved by the customer and installed at
their site. The most important document of this phase is probably the test report that (hopefully) confirms that the application
system is solving the problems it is required to.
The Data Model of the Project Manager
To be able to generate suitable documentation for all the previously mentioned project development phases, we have focused
on the following elements of the Designer Repository, plus a few elements that we had to add.
VISION ELEMENTS
In the vision phase there is a need for managing general information about the application. It must also be possible to include
external documents from other sources and define general business terms and definitions that will be used in the
documentation of the application. The Designer Repository already manages these elements (see Figure 1).
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 1
Application Systems
The application system is the core element of the Designer Repository. Here it is possible to define a short internal name for
the application (Name) and a more official title (Display Title). It is also possible to define a short general description of the
application (Summary) and a more complete description (Description).
Business Terms
It is good to have one place to define terms that are used throughout the documentation. By doing this it is neither necessary
to explain these terms every time they are used nor to force people to read the documentation in a specific order. In Designer,
the terms are simply defined as the name of the term and a related description or definition.
Designer’s ability to define Short Cuts allows you to define general terms in one central application system and reuse them in
multiple application systems. This means that when such a term is clarified or redefined some time in the future, the new
definition will automatically spread to all applications where that term was used.
Documents
In the vision phase there will usually already be documents related to the application that are not created by Designer but
come from external sources such as users, managers, customers, etc.
Usually the pitch document (the document that initiates the development project) will be an e-mail or a Word document (it
could even be someone’s good idea for a new system written down on a used napkin).
In Designer the Document element type represent all types of documents. Simple documents can be placed in the Document
Text property, and more advanced documents like Excel spreadsheets and MS Word documents can be referenced using the
Source Path property.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
ANALYSIS ELEMENTS
The next thing that happens in the project development process is that the requirements for the application are gathered, a
preliminary time plan is set up and the project group is defined (see Figure 2—note that we have added the red tables to the
Designer Repository). There will also be use for Designer’s analysis tools like ER diagrams, function hierarchies, etc.
Figure 2
Objectives
The system requirements can be stored as Objectives in the Designer Repository. These have a Name, a Status, a
Description, and some properties for defining the resources usage.
Objectives can also be related to Documents. By doing this you can document the sources of each requirement by including
minutes of meetings, e-mail, etc., that have been used to form or change the requirements as Documents and relate them to
the requirements they have impacted.
Problems
Problems is a very simple structure in Designer. It allows you to define a start and end date for a named problem. We have
chosen to use this structure for defining time plans or milestones..
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Problems can be structured in a hierarchy, which can be used to define general as well as detailed time plans that can easily
be extracted to MS Project Gantt diagrams.
Entities
Entities can be used in two ways. Primarily they are used for ER diagrams, but as these usually represent the central elements
of the system they should also be included in the list of Business Terms. The description of Entities is of much better use in the
list of Business Terms than as table descriptions that will only be read by developers.
Functions
The elementary functions (i.e., the leaf functions of the function hierarchy) will usually be suitable as requirements since they
represent things that the system must be able to do at the most detailed level.
As this might not always be the case, we have not chosen to use Functions as a requirement directly but have made a simple
utility to copy the content of Function elements onto Objective (requirement) elements.
Project Roles and Application Resources
We have added the following two tables outside the Designer Repository for managing project groups:
• Project Roles: This table contains all the person-types that can be involved in a project together with a detailed
description of the responsibilities of each role.
• Application Resource: This table defines who is assigned to which development project and
• with which role.
DESIGN ELEMENTS
Now that the requirements are in place we need to find out how to implement them in an application system. This means we
need to be able to document all the modules that need to be made (see Figure 3).
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 3
Modules
All general information about the modules is documented in the Modules elements. This can include information on how
complex the module will be to implement and how much progress has been made.
By creating System Objectives of Modules in the RON it is possible to link the Objectives (requirements) to the Modules to
document how each requirement is implemented by one or more modules. Later, this will also help you find the reason why a
specific module was made.
Module Components
Information related to the individual data blocks is documented in the Module Components element.
Items
Detailed information about the individual items of modules is documented in the Items element.
IMPLEMENTATION ELEMENTS
When implementing an application system it is necessary to create user documentation and test plans (see Figure 4). At this
point it is also necessary to document how the database was implemented.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 4
Test Steps
By defining the test plan through a detail relationship to the requirements we make sure that we test exactly the parts of the
system that the customer is interested in. This focus makes it much easier to find out what tests are relevant for the customer
(and hence the project).
By dividing each test step into the following properties we will be able to reuse the test plan as a tutorial document for the end
users:
1. Headline
2. Preconditions
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
3. Test description
4. Expected result
I will get back to the relation between the test plan and the tutorial in the section about generating documentation.
Table Definitions
The Designer Repository is filled with elements that describe the database objects, you just need to decide on the level of
detail that you want to include in your documentation.
ELEMENTS FOR TEST AND DELIVERY
The test report and the user’s reference guide can be made from the data model described previously. We just need an extra
multiline text property on the Application System element for the conclusion of the test report. This can be added as a User
Extension.
The Documents
This section describes the documents that can be generated from the data model described in the previous section and how
much work there is to be saved by exploiting the model.
Among the advantages of generating documents from a repository are:
1. The documents automatically get a structured and uniform look.
2. You don’t have to write repetitive text sections as these can be generated automatically.
3. You don’t have to spend time formatting your documents. Everything you enter is pure ASCII text so that the document
generator can control the formatting.
4. When your document standard changes with time you don’t have to change all earlier documents. Instead you can just
generate them again after you have updated the document generator.
There are many ways to generate documents from the Designer Repository. You can use Designer’s own Reports Generator
or the Web Server Generator. You can also build your own generator that reads the repository data and creates files in RTF,
MS Word, HTML, XML, or any other format that you like.
We have chosen to generate documents in MS Word format because it is a very well known format that most people are
familiar with. This format also has an easy way of building table of contents and indexes.
For details of how our MS Word generator works, read my paper on generating MS Word documents from Designer. You can
get it from the ODTUG Designer Tools Corner (www.odtug.com/tool.htm).
THE VISION PHASE
The following documents should be created in the vision phase.
The Pitch Document-L3
The pitch document usually comes from an external person and is therefore just stored as an element of type Document. It
only takes a few seconds to create such a reference to an external document in Designer. If the pitch document is just a
simple e-mail or note, it should be copied directly into the Summary property of the Application System. The pitch document
allows the ability to look back and see the application’s original background.
The Vision Document
The vision phase is completed when the vision document is approved and signed by the related parties. The vision document
contains the Summary and the full Description of what the requested application should be able to do. The vision document
could also contain definitions of system-specific terms and an appendix with other relevant documents that have emerged
during the vision phase.
The only actual documentation work that lies in the vision phase is the writing of the Application System Description (and the
Summary if it wasn’t copied from the pitch document). As describing the application already is the main task of the vision
phase, this cannot be considered extra work.
The definition of Business Terms only happens when terms from the Description need to be explained. By storing the term
definitions as Business Terms they will be easy to find and reuse in other parts of the project documentation and even in other
projects.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
THE ANALYSIS PHASE
The following documents should be created in the analysis phase.
The Time Plan
The time plan, which is made from the milestones defined as Problems elements, are generated as a simple data file for MS
Project, so that the result becomes a nice MS Project Gantt diagram.
The milestones are predefined by our development standard—actually they each represent the delivery of a project document.
That means that the time plan structure is automatically generated by a simple Designer API function. The remaining work is
reduced to absolute minimum, namely to fill in the estimated start and end dates of each milestone, without any tedious
documentation tasks.
The Requirements Document
We have chosen to use the Summary and Description from the vision document as the introduction to the requirements
document for three reasons:
1. The text is already written.
2. It is a natural introduction to the more detailed descriptions of every system requirement.
3. If important new requirements are revealed during the analysis phase, this is an opportunity to have the Application
System Description updated and presented to all project members without having to approve and sign a new version of
the vision document.
The next section of the requirements document is a preliminary time plan containing the estimated milestones and total
resource estimate (generated as the sum of each requirement’s resource estimate).
The main section shows each requirement (Objective) definition with its references to the external documents (Documents)
that lead to its definition. The external documents are placed as an appendix at the end of the document.
The requirements have a table of contents and an index where it is possible to look up the milestones, requirements, external
documents, etc., in alphabetical order. The requirements document becomes quite elaborate but the only work needed is to
define the requirements and link them to all the related external documents. Again, there is no extra work related to providing a
professional requirements document other than finding out what the customer wants the system to do, which is the whole
purpose of the analysis phase.
The Project Group Document
Only two things need to be registered for each project member to be able to generate the project group document:
1. The initials of the project member (or some other ID)
2. The name of the member’s role in the project
The document will contain a detailed description of each role’s responsibilities and the project members will be grouped under
these. At the end of the document there will be lines for the approvers’ signatures. Again, the actual work that needs to be
done to generate the documentation is the absolute minimum. There is no overhead related to producing the official project
group document.
THE DESIGN PHASE
The following documents should be created in the design phase.
The Design Document
An important milestone in the design phase is writing the design document. In parallel with the requirements document, we
have chosen to use the Application System Summary and Description for the introduction because important design decisions
could make it necessary to change the system Summary or Description.
The next section shows all the requirements and the third section shows all the designed modules with references to which
requirement(s) they solve. The modules could be created from Business Functions by the Application Design Transformer or
they could be created manually. In any case, they must contain a description of their function.
The appendix will contain all related external documents, as more will probably have been added during the design phase. Of
course the document also contains a table of contents and an index.
THE IMPLEMENTATION PHASE
The following documents should be created in the implementation phase.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
The Test Plan Document
We have chosen to let the structure of the test plan follow the requirements so that the customer can recognize that what is
being tested is actually what they have asked for.
Every requirement becomes a section in the test plan document and under each requirement there will be a number of test
steps each defined by a headline that indicates what that specific test step is testing.
Each test step will consist of the following elements:
1. Headline
2. Preconditions
3. Test process
4. Expected result
Each section contains lines for the test person and an approver to sign that the test was performed.
Because the test plan follows the structure of requirements it is much easier to determine how it should be made than if it had
to be made from scratch. In addition, the test plan can be reused for the tutorial manual.
The Tutorial Mannual
As soon as the test plan has been made the tutorial manual can be generated without any further work being done.
The tutorial manual uses the Application System Summary and Description as the introduction. This is the fifth reuse of those
two elements and the introduction will give the user a general idea of what the application is about. After that we have a
section for each requirement and a subsection for each test step within each requirement section. The contents of the
subsections will not be the entire test step but only:
1. Headline
2. Test process
An example would be:
Headline: Adding a new person to the system
Test process:
Enter the main menu
Select the Manage Persons screen
Click the Insert Record icon
Enter the person’s first name (ex. John)
Enter the person’s last name (ex. Doe)
Click on the Save icon
The text is taken directly from the test plan, but without the preconditions and the expected results it becomes a step-by-step
tutorial that explains how everything can be done with the system.
This symbiotic relationship between the test plan and the tutorial manual helps developers to remember to test all relevant
parts of the system. If something is left out of the test plan but is so important that it needs to be in the tutorial it is
automatically a part of the test plan as soon as it is added..
The table of contents and the index are absolutely crucial to this document so that the user can look up all the headlines either
sorted by functionality (in the table of contents) or alphabetically (in the index).
The User’s Reference Guide
The user’s reference guide contains everything that is not included in the tutorial. It contains the general descriptions of each
module, its module components, and items.
The reference guide can be made available on-line in the running application, so that the user can easily access information
about the screen they have opened. The module descriptions have already been made during the design phase, while block
and item descriptions can be fetched from the underlying table and column descriptions.
There is some work related to going through all these descriptions and adjusting them to the individual modules, but it surely
beats having to write a user’s reference guide from scratch! At the same time this task will make it possible to generate MS
Help files with the MS Help Generator or HTML based Help using the generator described by Ken Atkins in his paper
“Generating an HTML-Based Context Help System from Oracle Designer” (you can download his paper from www.odtug.com).
We also include at least one screen shot of each module so that the user can recognize the module they are on. These screen
shots can be reused for the system document.
THE TEST AND DELIVERY PHASE
The following documents should be created in the test and delivery phase.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
The Test Report
The test report describes the conclusion of the test. You want the test to not reveal any errors in the system but often there
can be general comments about the way that the test went or about the result.
One could use the Notes property on the Application System element for the test conclusion, or a new property can be added
as a User Extension. The test report will then consist of this concluding item and some lines for approving the test report.
The signed test plan is added as an appendix to the test report.
The System Document
The system document describes the entire delivery, i.e., all delivered modules and the underlying data model. All this
information is accessible from the Designer repository so there are no additional documentation tasks to be done to generate
the system document.
Project Document Conclusion
Imagination is the only limit for using project information when it is stored in a relational repository. That is why Designer is a
perfect tool for managing projects.
Rather than keeping track of countless versioned documents and writing status reports, this approach allows you to generate
the documents that you need when you need them. You look up and maintain the information in the repository, most of which
is created automatically as a result of the development process.
Project Management Web Screens
This section describes web screens that we have built on top of the data model. These screens give project managers a
comprehensive view of the progress of each active development project, focusing on milestones, delivery dates, and resource
estimates.
ACTIVE APPLICATIONS
We have built a high level screen that shows an overview of all our active Application Systems, i.e. Application Systems with at
least one uncompleted requirement or milestone (see Figure 5).
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 5
The team usually has 10-20 ongoing applications that are either being built from scratch or are being updated or patched, so
this screen gives us a good overview of what we are expected to deliver in the future.
Current Activity
To help us get a broad idea of what is going on with each application we have given each project manager the duty to maintain
a short one-line description of what is currently being done on each project.
Outstanding Time
The overview screen also shows the amount of work that still needs to be done on each application.
By summing the resource estimates of each requirement we get the total estimated development time. To be able to follow the
progress on each requirement we have chosen to operate with the following five status codes for requirements:
1. Vision (0%)
2. Analysis (25%)
3. Development (50%)
4. Test (75%)
5. Completed (100%)
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
The numbers in brackets indicate the progress in the following way. Requirements with the Vision status count as untouched,
which means that the estimated resource requirement is considered the same as the remaining time. Requirements with the
Analysis status count as 25% completed, which means that the remaining time is considered to be 75% of the estimated
resource requirement. I hope you get the idea. Requirements marked as Completed count as having no remaining time.
By using this simple weighting the developers do not have to estimate the remaining time of all their tasks. They just have to
update the status value every time a requirement changes phase.
Delivery Dates
The overview screen also shows the date of the next delivery of each application. This date is chosen as either the earliest
delivery date for an uncompleted requirement or the earliest uncompleted milestone—whichever comes first.
Actually, the entire list of applications is ordered by these dates to give an idea of what is expected of us in the near future.
Notice that when the date of delivery passes (and the given task is still not completed) the overview screen shows the date in
red.
Single Application Overview
The link on the application short name leads to a page that shows the general description of that application and the list of
uncompleted requirements (see figure 6).
Figure 6
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
This list also shows the status, time estimate, and responsibility for each requirement. Each requirement is formed as a link to
a page that describes the given requirement (see Figure 7).
Figure 7
WORKSHEETS
Each requirement is assigned to a project group member who becomes responsible for completing the requirement. Therefore
we can make an on-line worksheet where all requirements and milestones assigned to an individual project group member is
listed (see Figure 8).
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 8
Corresponding to the Active Applications screen, the total remaining workload of the individual project group member is
calculated and shown on the screen. These estimates represent the total workload of the individual employee that could be
derived from a number of development projects.
It is possible to zoom in on the different tasks and see the full description of the requirement or milestone (see Figure 9). The
screen also shows lists over the tasks that have been completed within the last two months, which might be useful for
measuring productivity.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 9
REQUIREMENTS
A third screen makes it possible to list requirements independently of projects or project group members (see Figure 10 and
Figure 11). This screen is used for creating overviews of the status of all tasks. It can filter tasks on status, delivery dates, etc.
The screen could be used to see all tasks that have reached the test phase or tasks that have passed the delivery dates
without being completed, or to view all deliveries that are committed to a specific month.
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 10
www.odtug.com ODTUG 2003
Project Management with Designer de Oliveira
Figure 11
TIME PLANS
We have built a similar screen for viewing time plans (also called milestones), i.e., the individual deliveries of each project’s
time plan. The screen can give you an overview of things like:
1. What deliveries have been promised for a given period
2. What deliveries have not yet been completed
3. What deliveries have been completed within a given period
Conclusion
With powerful project management tools like the ones described in this article, Designer could truly be called a complete
lifecycle development tool.
It is not a lot of work to implement these things yourself but I am sure that more people would use a tool like Designer if it had
the project management tools built-in.
Of course, what I have described here is not the limit of what can be done. It would also be interesting to have tools to
evaluate completed projects so that we could learn from our experiences when starting new projects. And I can imagine that
even more advanced tools for keeping track of resource estimates and remaining time can be developed.
I hope to have inspired you to further investigate the project management possibilities of Designer.
About the Author:
Marc de Oliveira is system analyst at NNE, a Scandinavian reseller of DesignAssist, Designer coordinator for OUGDK
and ODTUG, and director of the ODTUG board. He has a M.Sc. degree in computer science from the University of
Copenhagen and has worked with Oracle products (mainly CASE and Designer) since 1989. Email: Marc@deOliveira.dk.
www.odtug.com ODTUG 2003
Related docs
