SG - OCD

OCD Explained, with Examples
OCD Guidance	Sample Documents & Resources
Purpose of an Operational Concept Document An Operational Concept Document (OCD) discloses to a development team and its project managment the concept that binds the development together. It attempts to answer the questions: What is the application's purpose? Who are the Users and what do they need? How will the application be structured? Are there other organizing principles? Is the project feasible with a reasonable budget and schedule? What should we be worried about? Are there other interesting things we should think about before we begin? An Example OCD Outline Cover Sheet with Project title, author's name, and date Executive Summary Briefly summarizes the architecture, uses, structure, and critical issues, with an emphasis on the issues. Introduction Discusses application obligations at a high level. Don't restate all the project requirements. Also covers organizing principles, and key architectural ideas. Uses Who are the users - developers, managers, quality assurance, test, marketing, customers, others? What do they expect from the application, are there any special design consequences of satisfying their needs. You would expect, perhaps, that managers will need something quite different from developers if you think they will use the application. In this section you want to consider ways the application might be extended, beyond its requirements, to lead to new products, to serve additional user groups, or to provide additional useful features. You also think about changes to the requirements that could make the application more robust or simpler. Most of these won't be addressed in the current project, but with this information the team may be able to build a better, more flexible application. You may choose to mock up one or more user interfaces. Doing that helps you think about the system activities and helps readers understand your concept quickly. Here's an Example: Project Center Use Cases. Partitions - discuss whole and then each of the major parts Each task becomes a package candidate. After you've decided which candidates to use, name the packages, show their interactions in package diagram(s), and discuss. Part of this section will be a list of packages with a statement of responsibilities for each, and some discussion of their interactions. Application Activities - one activity section for each major part Identify all the major tasks required of the application. Then break each task down into activities. Use activity diagrams and discussion to show the reader how the system operates. Are the activities different for some of the user groups? This is essentially a top-down, high-level design. Are there any special processing activities associated with key events? What parts of the application need to know about the events. Should the architecture be structured around event handling, or phases of computation, or organization of data, or input and output, or some other organizing principle? Critical Issues Think about critical issues for the application and its parts, and make an issue list with, for each issue, a statement of the issue, whether it's important, and what you propose the application design should do to mitigate the issue. Please don't cite trivial "issues". For example, it is extremely unlikely that network bandwidth will be a performance limitation. Performance issues will come from computational load, not the small delays required to send data around the network. It is also unlikely that memory is a problem. You can buy a terabyte of storage for a few hundred dollars. Of course, there may be a few applications where these are important issues. Critical issues often are associated with safety concerns for life (medical systems), wealth (banking), information (security), or reliability. Complexity of the application and having a lot of complex information internally or to be presented to the user are very common issues. For concerns about performance, you need to consider typical and extreme estimated loads (users, messages, file transfers, expensive computations), and make estimates of your application's ability to sustain those loads. Finally, you may have complexity or robustness issues. Your job as architect, is to identify all the critical issues, then propose solutions where you can, and schedule prototyping activities to explore solutions where you can't. Prototyping If you've done any prototyping, you will create an appendix for each prototype and provide there a description of the prototype, its inputs and outputs, and what you learned by building it. Organizing OCD Note that there is an implied organization for your document: Executive Summary that summarizes your concept - not what you did. Discuss the whole project Discuss each major part with uses, activities, and issues Very brief conclusion	Sample Diagrams Here we provide samples of the kinds of diagrams you are likely to use in an OCD. They are drawn from a variety of applications - you shouldn't expect them to have content relevant to a document you are preparing. They're listed in the order of importance for OCDs. Simple package diagram, More complex package Diagram First diagram shows packages in a test harness. Second illustrates packages in a Peer-to-Peer communicator. Activity Diagram Activities for passing messages in a Peer-to-Peer communication system. Class diagram This diagram shows interesting relationships between classes in a code parser. Ad Hoc Diagram Custom diagram showing parallel grammar processing in type analyzer. Sequence diagram Sequence diagram for a program that finds duplicate files in a directory tree. State diagram Example state diagram of a code analyzer. Structure Chart Function call relationships in a Test Harness server. Data Flow Diagram Data flow diagrams show associated groups of processes and the information flows into and out of each process. Every diagram in your document should be accompanied by text that answers the questions, perhaps indirectly: Why is this diagram here? What is it telling me? What conclusions should I draw from the diagram? You've heard that a picture is worth a thousand words. But that is true only if it is accompanied by a few paragraphs of text. Sample Uses Project Center Use Cases The Project Center was a Software Studio project, completed in 2004. It built a federated development environment by wrapping many existing open-source tools and a few custom tools in an infrastructure supporting network and web based collaboration. Sample OCDs Prepared by Former Students Example OCDs prepared by students, Fall 2018: Akshitha Koganti Christina Tobias Harika Bandaru Sachin Basavani Other References: Architectural Concept Document Survival Guide

OCD Explained, with Examples

OCD Guidance

Sample Documents & Resources

Purpose of an Operational Concept Document

An Operational Concept Document (OCD) discloses to a development team and its project managment the concept that binds the development together. It attempts to answer the questions:

What is the application's purpose?
Who are the Users and what do they need?
How will the application be structured?
Are there other organizing principles?
Is the project feasible with a reasonable budget and schedule?
What should we be worried about?
Are there other interesting things we should think about before we begin?

An Example OCD Outline

Cover Sheet with Project title, author's name, and date
Executive Summary
Briefly summarizes the architecture, uses, structure, and critical issues, with an emphasis on the issues.
Introduction
Discusses application obligations at a high level. Don't restate all the project requirements. Also covers organizing principles, and key architectural ideas.
Uses
Who are the users - developers, managers, quality assurance, test, marketing, customers, others? What do they expect from the application, are there any special design consequences of satisfying their needs. You would expect, perhaps, that managers will need something quite different from developers if you think they will use the application.
In this section you want to consider ways the application might be extended, beyond its requirements, to lead to new products, to serve additional user groups, or to provide additional useful features. You also think about changes to the requirements that could make the application more robust or simpler.
Most of these won't be addressed in the current project, but with this information the team may be able to build a better, more flexible application.
You may choose to mock up one or more user interfaces. Doing that helps you think about the system activities and helps readers understand your concept quickly.
Here's an Example: Project Center Use Cases.
Partitions - discuss whole and then each of the major parts
Each task becomes a package candidate. After you've decided which candidates to use, name the packages, show their interactions in package diagram(s), and discuss. Part of this section will be a list of packages with a statement of responsibilities for each, and some discussion of their interactions.
Application Activities - one activity section for each major part
Identify all the major tasks required of the application. Then break each task down into activities. Use activity diagrams and discussion to show the reader how the system operates. Are the activities different for some of the user groups? This is essentially a top-down, high-level design.
Are there any special processing activities associated with key events? What parts of the application need to know about the events. Should the architecture be structured around event handling, or phases of computation, or organization of data, or input and output, or some other organizing principle?
Critical Issues
Think about critical issues for the application and its parts, and make an issue list with, for each issue, a statement of the issue, whether it's important, and what you propose the application design should do to mitigate the issue.
Please don't cite trivial "issues". For example, it is extremely unlikely that network bandwidth will be a performance limitation. Performance issues will come from computational load, not the small delays required to send data around the network. It is also unlikely that memory is a problem. You can buy a terabyte of storage for a few hundred dollars. Of course, there may be a few applications where these are important issues.
Critical issues often are associated with safety concerns for life (medical systems), wealth (banking), information (security), or reliability. Complexity of the application and having a lot of complex information internally or to be presented to the user are very common issues. For concerns about performance, you need to consider typical and extreme estimated loads (users, messages, file transfers, expensive computations), and make estimates of your application's ability to sustain those loads. Finally, you may have complexity or robustness issues.
Your job as architect, is to identify all the critical issues, then propose solutions where you can, and schedule prototyping activities to explore solutions where you can't.
Prototyping
If you've done any prototyping, you will create an appendix for each prototype and provide there a description of the prototype, its inputs and outputs, and what you learned by building it.
Organizing OCD
Note that there is an implied organization for your document:
- Executive Summary that summarizes your concept - not what you did.
- Discuss the whole project
- Discuss each major part with uses, activities, and issues
- Very brief conclusion

Sample Diagrams

Here we provide samples of the kinds of diagrams you are likely to use in an OCD. They are drawn from a variety of applications - you shouldn't expect them to have content relevant to a document you are preparing. They're listed in the order of importance for OCDs.

Simple package diagram, More complex package Diagram
First diagram shows packages in a test harness. Second illustrates packages in a Peer-to-Peer communicator.
Activity Diagram
Activities for passing messages in a Peer-to-Peer communication system.
Class diagram
This diagram shows interesting relationships between classes in a code parser.
Ad Hoc Diagram
Custom diagram showing parallel grammar processing in type analyzer.
Sequence diagram
Sequence diagram for a program that finds duplicate files in a directory tree.
State diagram
Example state diagram of a code analyzer.
Structure Chart
Function call relationships in a Test Harness server.
Data Flow Diagram
Data flow diagrams show associated groups of processes and the information flows into and out of each process.

Every diagram in your document should be accompanied by text that answers the questions, perhaps indirectly:

Why is this diagram here?
What is it telling me?
What conclusions should I draw from the diagram?

You've heard that a picture is worth a thousand words. But that is true only if it is accompanied by a few paragraphs of text.

Sample Uses

Project Center Use Cases

The Project Center was a Software Studio project, completed in 2004. It built a federated development environment by wrapping many existing open-source tools and a few custom tools in an infrastructure supporting network and web based collaboration.

Sample OCDs Prepared by Former Students

Example OCDs prepared by students, Fall 2018:
Akshitha Koganti
Christina Tobias
Harika Bandaru
Sachin Basavani

Other References:

Architectural Concept Document Survival Guide