improve README and add story-based introduction (#190)

* improve README and add story-based introduction

* add platform arch diagram

* comments

* comments

README.md

@@ -1,30 +1,25 @@
 # Open Application Model Specification
 
-
 From the creators of 
 [Helm](https://helm.sh),
 [OpenKruise](https://openkruise.io/en-us/),
 and [Service Fabric](https://github.com/Microsoft/service-fabric),
 the Open Application Model is a specification for building cloud native applications.
 
-Focused on the separation of development concerns from operational considerations through a platform-agnostic application model, OAM provides a set of tools for building high-grade containerized applications
-on systems like Kubernetes.
-
 *This repository is unstable, and open to contributions.*
-The specification is under development, and breaking changes are made regularly.
+The specification is under development, and breaking changes could be made.
 Interested in contributing? Take a look at the issue queue! We're looking for more
 great ideas on how to model cloud native applications.
 
-## The Main Idea
+## Introduction
 
-When it comes to the practice of software development and deployment, we think it is
-important to distinguish between the parts of the software that developers are
-responsible for, and the parts that operations is responsible for. Too often,
-these roles get muddled, resulting in communications mishaps, bugs, or even
+![How it works][how-it-works]
+
+When it comes to application development and deployment, we think it is important to distinguish between the parts that developers are responsible for, and the parts that operations is responsible for. Otherwise, if these roles get muddled, it would result in communications mishaps, bugs, or even
 service outages.
 
-Hydra attempts to solve this problem by modeling the application according to the
-roles responsible for building and running apps and infrastructure.
+_Open Application Model_ attempts to solve this problem by modeling the application according to the
+roles responsible for building and running apps and operating infrastructure.
 
 * _Developers_ are responsible for describing what a microservice or component does,
   and _how_ it can be configured. They are the domain experts on the code.
@@ -35,32 +30,14 @@ roles responsible for building and running apps and infrastructure.
   infrastructure within which applications run. They are the domain
   experts on the low-level details.
 
-## How it works
-
-Hydra describes a model where developers are responsible for defining _components_,
-application operators are responsible for creating instances of those components and
-assigning them _application configurations_. And infrastructure operators are
-responsible for declaring, installing, and maintaining the underlying services that
-are available on the platform.
-
-![How it works][how-it-works]
-
-For example, a _developer_ creates web application. The _application operator_ creates
-an instance of that application, and configures it to autoscale with load. The
-_infrastructure operator_ decides which underlying autoscaling technology is
-used to do the scaling.
+For more details and user stories, see [introduction.md](./introduction.md).
 
 ## See it in action
 
-[Scylla](https://github.com/microsoft/scylla) is a reference implementation of the Open Application Model specification for Kubernetes. To get started with an example on the Open Application Model, go to the [Scylla](https://github.com/microsoft/scylla) repo getting started guide.
-
-## About This Repository
+[Scylla](https://github.com/microsoft/scylla) is a reference implementation of the Open Application Model specification for Kubernetes. To get started with an example on the Open Application Model, go to the [Scylla getting started](https://github.com/microsoft/scylla/blob/master/docs/quickstart/quickstart.md) guide.
 
-This repository contains the Open Application Model specification.
+## Specification
 
-## Table of Contents
-
-* The Hydra Application Specification
   1. [Purpose and Goals](1.purpose_and_goals.md)
   2. [Overview and Terminology](2.overview_and_terminology.md)
   3. [The Component Model](3.component_model.md)
@@ -72,7 +49,8 @@ This repository contains the Open Application Model specification.
   9. [Design Principles](9.design_principles.md)
   10. [Appendix A: Extended Workload Types](10.appendix-extended-workload-types.md)
 
-## Triaging and Milestones 
+
+## Community
 
 ### Milestones
 
@@ -82,7 +60,7 @@ To get an overview of the milestones and their description please visit the [Mil
 
 Triaging of items into milestones will occur during the bi-weekly community call. During this call, issues might be brought into milestones, removed from milestones or moved between milestones. 
 
-## Contributing
+### Contributing
 
 Hydra Specifications follow the [CNCF Code of Conduct][cncf-coc]. See the [CONTRIBUTING](contributing.md) guide for more information about submitting changes to the spec.
 
@@ -96,25 +74,6 @@ Below are links to join the bi-weekly community meetings and our meeting notes.
 | Slack Channel       | TBD  |
 | Meeting Notes       | https://docs.google.com/document/d/1nqdFEyULekyksFHtFvgvFAYE-0AMHKoS3RMnaKsarjs/edit?usp=sharing |
 
-## Notational Conventions
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be
-interpreted as described in [RFC 2119][rfc2119].
-
-The key words "unspecified", "undefined", and "implementation-defined" are to be
-interpreted as described in the [rationale for the C99
-standard][c99-unspecified].
-
-An implementation IS compliant if it satisfies all the MUST, REQUIRED, and SHALL
-requirements.
-
-An implementation IS NOT compliant if it fails to satisfy one or more of the
-MUST, REQUIRED, or SHALL requirements.
-
 [cncf-coc]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
-[rfc2119]: http://tools.ietf.org/html/rfc2119
-[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
-
 
 [how-it-works]: assets/how-it-works.png

introduction.md

@@ -0,0 +1,45 @@
+# Introduction
+
+This doc gives an introduction of the specification in a story-based format. It help end users and developers to quickly understand and implement the protocol.
+
+In the following, we are going through a story of application delivery lifecycle. The storyline goes as:
+
+1. The _developer_ creates a web application;
+2. The _application operator_ deploys instances of that application, and configures it with operation traits, e.g. autoscaling;
+3. The _infrastructure operator_ decides which underlying technology is used to handle the deployment and operations.
+
+## App Developer: Develop Apps
+
+First of all, we have developers who create an online shopping app. They know how to write and test the code. The program takes a few parameters: log level, http port, metrics port. To let the developers focus on development, application operators (either human or automated operation platforms) takes care of the operational tasks. This provides a "serverless" experience to the developers. But, the developers still need to develop and package the application, and deliver it to the application operators.
+
+How app developers deliver it? The answer is that they will define a _ComponentSchematic_ yaml. In _Open Application Model_, each piece of program is described as a _ComponentSchematic_ yaml by app developer. Any information that app operator needs to know about the program will be defined within. For example, the container image packaging the program and the program parameters will be written in a _ComponentSchematic_ yaml. 
+
+The below diagram demonstrates the workflow:
+
+![alt](./assets/dev2ops.png)
+
+## App Operator: Deploy and Maintain Apps
+
+Deploying an application requires runtime traits configuration and live instances deployment. The app operator applies runtime configuration like replica size, autoscaling policy, which cluster to deploy in a _ApplicationConfiguration_ yaml. Writing and deploying a _ApplicationConfiguration_ yaml is equivalent to deploying an app. The underlying platform will create live instances of _ComponentSchematic_ and attach operational traits to them according to the _ApplicationConfiguration_ spec.
+
+The below diagram demonstrates the workflow:
+
+![alt](./assets/ops-deploy-app.png)
+
+## Infra Operator: Configure Platform Capabilities
+
+Now that the app operator deploys a _ComponentSchematic_ yaml. How does it happen in real? The power comes from the underlying platforms.
+
+Each platform provides a group of application deployment and operational capabilities. Infrastructure operators are responsible for declaring, installing, and maintaining the underlying services that are available on the platform. For example, infra operator might choose the Load Balancer technology of a specific cloud provider to expose the service.
+
+The below diagram demonstrates the platform architecture:
+
+![alt](./assets/platform_arch.png)
+
+[Scylla](https://github.com/microsoft/scylla) is a reference implementation based on Kubernetes. Give it a try to gain hands-on experience.
+
+## The Benefits? Portable Apps!
+
+Focused on the separation of development concerns from operational considerations through a platform-agnostic application model, Open Application Model provides a set of tools for building portable containerized applications on systems like Kubernetes.
+
+For end users, they enjoy portable apps across platforms. If an app could be deployed and used on one provider, it should be able to on any other providers. We define must-implement, recommended, and candidate types in _core_, _standard_, and _extended_ APIs. This will ensure portability and provide extensibility in the same spec. Of course, not everything is portable and the primary concern of such an interface is that it is a "lowest-common denominator". Our aspiration is to build a vendor-neutral, community-owned spec and the most popular APIs will be embraced and added to the specification over time. In this way, the evolution will ensure that most users will be successful in building cloud native applications via the Open Application Model.

notational_convention.md

@@ -0,0 +1,18 @@
+# Notational Conventions
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be
+interpreted as described in [RFC 2119][rfc2119].
+
+The key words "unspecified", "undefined", and "implementation-defined" are to be
+interpreted as described in the [rationale for the C99
+standard][c99-unspecified].
+
+An implementation IS compliant if it satisfies all the MUST, REQUIRED, and SHALL
+requirements.
+
+An implementation IS NOT compliant if it fails to satisfy one or more of the
+MUST, REQUIRED, or SHALL requirements.
+
+[rfc2119]: http://tools.ietf.org/html/rfc2119
+[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18