diff --git a/docs/core-concepts/apps.md b/docs/core-concepts/apps.md
index a5c617fe0..c623ced75 100644
--- a/docs/core-concepts/apps.md
+++ b/docs/core-concepts/apps.md
@@ -1 +1,277 @@
 # Apps
+
+## 1 Concept
+
+An app in DevStream corresponds to a real-world application, and the app represents the whole software development lifecycle of that app, including source code management, code scaffolding, CI/CD (and their pipelines).
+
+Using "App", you can easily create these for an application.
+
+### 1.1 Apps
+
+There are situations where you need to define multiple DevOps tools for an application/microservice. For example, for a web-app typed microservice, you might need the following:
+
+- source code management, code repo scaffolding
+- continuous integration (the installation of the DevOps tool, the creation of the CI pipeline)
+- continuous deployment (the installation of the DevOps tool, the creation of the CD pipeline)
+
+If you are managing more than one application/microservice (chances are, you will be managing more than one application in the real world), the configuration of DevStream can be quite long, hard to read and hard to manage if you are only using "Tools". 
+
+In order to solve this problem, DevStream provides another concept that is "App". You can easily define all DevOps tools and pipelines for an App with a couple of lines of YAML config, making the config file much easier to read and manage.
+
+In essence, "App" will be converted to "Tool", which you do not have to worry about at all; let DevStream handle that.
+
+## 1.2 pipelineTemplates
+
+pipelineTemplates define CI/CD pipelines, so that they can be referred to and shared by different DevStream Apps, reducing the length of the config file to the next level.
+
+## 2 Config
+
+### 2.1 App
+
+In the config, there is a `apps` section, which is a list, with each element having the following keys:
+
+- name: the name of the app, unique
+- spec: application-specific information
+- repo: info about the code repository
+- repoTemplate: optional, same structure as "repo". If empty, DevStream will create/scaffold a repository from scratch.
+- ci: optional, a list of CI pipelines, each element can have the following keys:
+    - type: the value can be a `template` or the name of a plugin
+    - templateName: optional, if type is `template`, it defines which pipelineTemplate to use
+    - vars: optional, variables to be passed to the template. Only works when type is `template`, apparently
+    - options: optional
+        - if type is the name of a plugin, the options are the options of that plugin
+        - if type is `template`, the options here will override the ones in the template. Use full path to override, for example, `options.docker.registry.type`
+- cd: like `ci`, but stands for the list of CD pipelines. DevStream will execute CI first before CD
+
+### 2.2 pipelineTemplate
+
+Defined in the `pipelineTemplates` of the config, it's a list, with each element having the following keys:
+
+- name: unique name of the pipelineTemplate, unique
+- type: corresponds to a plugin's name
+- options: options for that plugin
+
+### 2.3 Local Variables
+
+DevStream has a "var" section in the config, serving as global variables that can be referred to by all Tools and Apps.
+
+Sometimes, however, we'd like to use the same DevOps tool with minor differences. For example, except the name of the project, everything else is different.
+
+In this case, we can define a pipelineTemplate with a local variable, and when referring to it, we can pass different values to it:
+
+```yaml hl_lines="13 15 23 30" title="pipelineTemplate and local variables"
+apps:
+- name: my-app
+  spec:
+    language: java
+    framework: springboot
+    repo: 
+      url: https://github.com/testUser/testApp.git
+      branch: main
+    ci:
+    - type: github-actions # use a plugin directly without defining pipelineTemplates
+    cd:
+    - type: template # use a pipelineTemplate
+      templateName: my-cd-template # corresponds to the name of the pipelineTemplate
+      vars:
+        appName: my-app # a local variable passed to the pipelineTemplate
+
+pipelineTemplates:
+cd:
+- name: my-cd-template
+  type: argocdapp
+  options:
+    app:
+      name: [[ appName ]] # a local variable, passed to when referring to the template
+      namespace: argocd
+    destination:
+      server: https://kubernetes.default.svc
+      namespace: default
+    source:
+      valuefile: values.yaml
+      path: charts/[[ appName ]]
+```
+
+## 3 A Demo of the Whole Config
+
+A whole config for an App:
+
+```yaml
+apps:
+- name: testApp # name of the app
+  spec: # app-specific info
+    language: java # programming language of the app
+    framework: springboot # framework of the app
+  repo: # repository-related info for the app
+    url: https://github.com/testUser/testApp.git
+    branch: main
+  repoTemplate: # optional, used for repository bootstrapping/scaffolding. If not empty, a repo will be created with scaffolding code
+    url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
+    vars:
+      imageRepoOwner: repoOwner # variables used for repoTemplate
+  ci: # CI pipelines, here we use github-actions
+  - type: github-actions
+- name: testApp2
+  spec:
+    language: go
+    framework: gin
+  repo: # repository-related info for the app
+    owner: test_user
+    type: github
+    branch: main
+  repoTemplate: # optional, used for repository bootstrapping/scaffolding. If not empty, a repo will be created with scaffolding code
+    org: devstream-io
+    name: dtm-repo-scaffolding-java-springboot
+    type: github
+  ci: # CI pipelines, here we use github-actions
+  - type: github-actions
+    options:
+      imageRepo:
+        owner: repoOwner # override the plugin's options. Must use full YAML path.
+  cd: # CD pipelines, here we use argocd
+  - type: argocdapp
+```
+
+If we apply this config, DevStream will create two repositories in GitHub, with scaffolding code provided by DevStream [SpringBoot](https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git). App `testApp` will trigger CI in GitHub Actions upon each commit, and App `testApp2` will trigger build/push in GitHub Actions upon commit, and deploy using Argo CD.
+
+### repo/repoTemplate Config
+
+The `repo` and `repoTemplate` in the Config represent a code repository. You can define it with a single URL or a few key/values:
+
+!!! note "two ways to configure code repo"
+
+    === "using a single URL"
+    
+        ```yaml title=""
+          repo:
+            url: git@gitlab.example.com:root/myapps.git # repo URL, supports both git and https
+            apiURL: https://gitlab.example.com # not mandatory, if using gitlab and the URL protocol is git, here can be the GitLab API URL
+            branch: "" # not mandatory, defaults to main for GitHub and master for GitLab
+        ```
+    
+        This example shows that we use GitLab `git@gitlab.example.com:root/myapps.git` for code clone, and DevStream uses `https://gitlab.example.com` to access GitLab API. Default branch is master.
+    
+    === "using detailed key/value config for the repo"
+    
+        ```yaml title=""
+          repo:
+            org: "" # only mandatory for GitHub organization
+            owner："test_user" # if the repo belongs to a person. If the repo belongs to an org, use the org above.
+            name: "" # optional, defaults to the name of the app
+            baseURL:  https://gitlab.example.com # optional. If GitLab, here we can put the GitLab domain.
+            branch: master # not mandatory, defaults to main for GitHub and master for GitLab
+            type:  gitlab # mandatory, either gitlab or github
+        ```
+    
+        This example shows that we use GitLab `https://gitlab.example.com`, repo name is the app name, belongs to owner `test_user`, with the default branch being "master".
+
+### CI Config
+
+The `CI` section in the config supports 4 types at the moment: `github-actions`/`gitlab-ci`/`jenkins-pipeline`/`template`.
+
+`template` means to use a pipelineTemplate; and the other three types correspond to GitHub Actions, GitLab CI, and Jenkins, respectively.
+
+Detailed config:
+
+```yaml
+  ci:
+  - type: jenkins-pipieline # type of the CI
+    options: # options for CI. If empty, CI will only run unit test.
+      jenkins: # config for jenkins
+        url: jenkins.exmaple.com # jenkins URL
+        user: admin # jenkins user
+      imageRepo: # docker image repo to be pushed to. If set, Ci will push the image after build.
+        url: http://harbor.example.com # image repo URL. Defaults to dockerhub.
+        owner: admin # image repo owner
+      dingTalk: # dingtalk notification settings. If set, CI result will be pushed to dingtalk.
+        name: dingTalk
+        webhook: https://oapi.dingtalk.com/robot/send?access_token=changemeByConfig # callback URL for dingtalk.
+        securityType: SECRET # use secret to encrypt dingtalk message
+        securityValue: SECRETDATA # dingtalk secret encryption data
+      sonarqube: # sonarqube config. If set, CI will test and execute sonarqube scan.
+        url: http://sonar.example.com # sonarqube URL
+        token: YOUR_SONAR_TOKEN # soanrqube token
+        name: sonar_test
+```
+
+The config above will trigger unit test and sonarqube code scan upon commit, then a Docker image will be built and pushed to dockerhub, and the result of the CI will be pushed to dingtalk.
+
+If the same pipeline is required for multiple apps, the config can be long and redundant. So, DevStream provides the `template` type to share similar settings for diffrent Apps. Detailed example:
+
+```yaml
+apps:
+- name: javaProject1
+  spec:
+    language: java
+    framework: springboot
+  repo:
+    owner: testUser
+    type: github
+  repoTemplate:
+    url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
+  ci:
+  - type: template # use a pipelineTemplate
+    templateName: ci-pipeline # name of the pipelineTemplate
+    vars:
+      dingdingAccessToken: tokenForProject1 # variables for the pipelineTemplate
+      dingdingSecretValue: secretValProject1
+- name: javaProject2
+  spec:
+    language: java
+    framework: springboot
+  repo:
+    owner: testUser
+    type: github
+  repoTemplate:
+    url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
+  ci:
+  - type: template # use a pipelineTemplate
+    templateName: ci-pipeline # name of the pipelineTemplate
+    vars:
+      dingdingAccessToken: tokenForProject2 # variables for the pipelineTemplate
+      dingdingSecretValue: secretValProject2
+
+pipelineTemplates: # CI/CD pipeline templates
+- name: ci-pipeline # name of the pipelineTemplate
+  type: jenkins-pipeline # type, supports jenkins-pipeline，github-actions and gitlab-ci at the moment
+  options: # options, same as CI options
+    jenkins:
+      url: jenkins.exmaple.com
+      user: admin
+    imageRepo:
+      url: http://harbor.example.com
+      owner: admin
+    dingTalk:
+      name: dingTalk
+      webhook: https://oapi.dingtalk.com/robot/send?access_token=[[ dingdingAccessToken ]] # local variable, passed to when referring to this template
+      securityType: SECRET
+      securityValue: [[ dingdingSecretValue ]] # local variable, passed to when referring to this template
+    sonarqube:
+        url: http://sonar.example.com
+        token: sonar_token
+        name: sonar_test
+
+```
+
+If we apply the above config, we will create two Jenkins pipelines for two apps, with the only difference being that the dingtalk notification will be sent to different groups.
+
+### CD Config
+
+At the moment, CD only supports `argocdapp`. Argo CD itself can be deployed with a Tool, and `argocdapp` is responsible for deploying the app in a Kubernetes cluster.
+
+Detailed config example:
+
+```yaml
+cd:
+- type: argocdapp
+  options:
+    app:
+      name: hello # argocd app name
+      namespace: argocd # argocd namespace
+    destination:
+      server: https://kubernetes.default.svc # Kubernetes cluster
+      namespace: default # which namespace to deploy the app
+    source:
+      valuefile: values.yaml # helm values file
+      path: charts/go-hello-http # helm chart path
+```
diff --git a/docs/core-concepts/apps.zh.md b/docs/core-concepts/apps.zh.md
index 37e7cf82e..9d417f1ae 100644
--- a/docs/core-concepts/apps.zh.md
+++ b/docs/core-concepts/apps.zh.md
@@ -259,10 +259,10 @@ cd:
 - type: argocdapp
   options:
     app:
-      name: hello # argocd 引用名称
+      name: hello # argocd 应用名称
       namespace: argocd # argocd 的命名空间
     destination:
-      server: https://kubernetes.default.svc # 部署的 kubernetes 服务地址
+      server: https://kubernetes.default.svc # 部署的 Kubernetes 服务地址
       namespace: default # 应用要部署的命名空间
     source:
       valuefile: values.yaml # 项目中的 helm 变量文件名
diff --git a/docs/core-concepts/config.md b/docs/core-concepts/config.md
index c41852af0..2f4b78668 100644
--- a/docs/core-concepts/config.md
+++ b/docs/core-concepts/config.md
@@ -1,14 +1,10 @@
 # Config
 
-Now let's have a look at some config examples.
+DevStream uses YAML files to define your DevOps platform.
 
-TL;DR: [see the complete config file examle at the end of this doc](#7-putting-it-all-together).
+## Sections
 
----
-
-## 1 The Config File
-
-As mentioned in the overview section, the main config contains many sections, like:
+As aforementioned in the overview, there are several sections in the config:
 
 - `config`
 - `vars`
@@ -16,270 +12,56 @@ As mentioned in the overview section, the main config contains many sections, li
 - `apps`
 - `pipelineTemplates`
 
-By default, `dtm` tries to use `./config.yaml` (under your working directory) as the main config.
+Among which, `config` is mandatory, and you should have at least either `tools` or `apps`. Others are optional.
 
-You can override the default value with `-f` or `--config-file`. Examples:
+## Config File V.S. Config Folder
 
-```shell
-dtm apply -f path/to/your/config.yaml
-dtm apply --config-file path/to/your/config.yaml
-```
+DevStream supports both:
 
----
+- a single config file: put all sections of the config into one YAML file
+- a directory: put multiple files in one directory, as long as the file names end with `.yaml` or `.yml`
 
-## 2 State Config
+When you run the `init` (or other commands), add `-f` or `--config-file`.
 
-The `config` section specifies where to store the DevStream state.
+Examples:
 
-### 2.1 Local
+- single file: `dtm init -f config.yaml`
+- directory: `dtm init -f dirname`
 
-```yaml
-config:
-  state:
-    backend: local
-    options:
-      stateFile: devstream.state
-```
+## The Main Config
 
-_Note: The `stateFile` under the `options` section is mandatory for the local backend._
+DevStream's own config, the `config` section, contains where to store the state. See [here](./state.md) for more details.
 
-### 2.2 Kubernetes
+## Variables
 
-```yaml
-config:
-  state:
-    backend: k8s
-    options:
-      namespace: devstream # optional, default is "devstream", will be created if not exists
-      configmap: state     # optional, default is "state", will be created if not exists
-```
+DevStream supports variables. Define key/values in the `vars` section and refer to it in the `tools`, `apps` and `pipelineTemplates` sections.
 
-### 2.3 S3
+Use double square brackets when referring to a variable: `[[ varName ]]`.
 
-```yaml
-config:
-  state:
-    backend: s3
-    options:
-      bucket: devstream-remote-state
-      region: ap-southeast-1
-      key: devstream.state
-```
-
-_Note: the `bucket`, `region`, and `key` under the `options` section are all mandatory fields for the s3 backend._
-
----
-
-## 3 Variables
-
-To not repeat yourself (Don't repeat yourself, DRY, see [here](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself),) we can define some variables in a var file and use the vars in the config file.
-
-The vars section is a YAML dict containing key-value pairs. Example:
-
-Example:
+example:
 
 ```yaml
 vars:
-  repoOwner: RepoOwner
-  repoTemplateBaseURL: github.com/devstream-io
-  imageRepoOwner: ImageRepoOwner
-```
-
-To use these variables in a config file, use the following syntax:
+  githubUsername: daniel-hutao # define a variable
+  repoName: dtm-test-go
+  defaultBranch: main
 
-```yaml
-[[ varNameHere ]]
-```
-
----
-
-## 4 Tools
-
-The tools section contains a list of tools.
-
-```yaml
 tools:
 - name: repo-scaffolding
-  instanceID: myapp
-  options:
-    destinationRepo:
-      owner: [[ githubUser ]]
-      name: [[ app ]]
-      branch: main
-      scmType: github
-    sourceRepo:
-      org: devstream-io
-      name: dtm-scaffolding-python
-      scmType: github
-    vars:
-      imageRepo: [[ dockerUser ]]/[[ app ]]
-- name: github-actions
   instanceID: default
-  dependsOn: [ repo-scaffolding.myapp ]
   options:
-    scm:
-      owner: [[ githubUser ]]
-      name: [[ app ]]
-      branch: main
+    destinationRepo:
+      owner: [[ githubUsername ]] # refer to the pre-defined variable
+      name: [[ repoName ]]
+      branch: [[ defaultBranch ]]
       scmType: github
-    pipeline:
-      language:
-        name: python
-        framework: flask
-      imageRepo:
-        user: [[ dockerUser ]]
-- name: helm-installer
-  instanceID: argocd
-- name: argocdapp
-  instanceID: default
-  dependsOn: [ "helm-installer.argocd", "github-actions.default" ]
-  options:
-    app:
-      name: [[ app ]]
-      namespace: argocd
-    destination:
-      server: https://kubernetes.default.svc
-      namespace: default
-    source:
-      valuefile: values.yaml
-      path: helm/[[ app ]]
-      repoURL: ${{repo-scaffolding.myapp.outputs.repoURL}}
+    # ...
 ```
 
-If you want tool A to be installed before tool B, you can let tool B depend on tool A.
+## Tools Config
 
-The syntax for dependency is:
+The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail.
 
-```yaml
-dependsOn: [ "ToolName.ToolInstanceID" ]
-```
+## Apps/pipelineTemplates Config
 
-Since `dependsOn` is a list, a tool can have multiple dependencies:
-
-```
-dependsOn: [ "ToolName1.ToolInstanceID1", "ToolName2.ToolInstanceID2", "..." ]
-```
-
----
-
-## 5 Apps
-
-The Apps section looks like the following:
-
-```yaml
-apps:
-- name: service-A
-  spec:
-    language: python
-    framework: django
-  repo:
-    scmType: github
-    owner: devstream-io
-    org: devstream-io # either owner or org must exist
-    name: service-A   # defaults to "app.name"
-    url: github.com/devstream-io/repo-name   # optional. if exists, no need for the scm/owner/org/name sections
-    apiURL: gitlab.com/some/path/to/your/api # optional, in case of self-managed git
-  repoTemplate:   # optional. if repoTemplate isn't empty, create repo according to the template
-    scmType: github
-    owner: devstream-io
-    org: devstream-io # either owner or org must exist
-    name: dtm-repo-scaffolding-golang
-    url: github.com/devstream-io/repo-name   # optional. if exists, no need for the scm/owner/org/name sections
-    vars:  # optional
-      foo: bar  # variables used for repoTemplate specifically
-  ci:
-  - type: template              # type template means it's a reference to the pipeline template. read the next section.
-    templateName: ci-pipeline-1
-    options: # optional, used to override defaults in the template
-    vars:    # optional, key/values to be passed to the template
-      key: value
-  cd:
-  - type: template              # type template means it's a reference to the pipeline template. read the next section.
-    templateName: cd-pipeline-1
-    options: # optional, used to override defaults in the template
-    vars:    # optional, key/values to be passed to the template
-      key: value
-```
-
-Since many key/values have default values, it's possible to use the following minimum config for the apps section:
-
-```yaml
-apps:
-- name: myapp1
-  spec:
-    language: python
-    framework: django
-  repo:
-    url: github.com/ironcore864/myapp1
-  repoTemplate:
-    url: github.com/devstream-io/dtm-repo-scaffolding-python
-  ci:
-  - type: github-actions
-  cd:
-  - type: argocdapp
-```
-
----
-
-## 6 Pipeline Templates
-
-You can define some pipeline templates in the pipelineTemplates section:
-
-```yaml
-pipelineTemplates:
-- name: ci-pipeline-1
-  type: github-actions # corresponds to a DevStream plugin
-  options:
-    branch: main      # optional
-    docker:
-      registry:
-        type: dockerhub
-        username: [[ dockerUser ]]
-        repository: [[ app ]]
-- name: cd-pipeline-1
-  type: argocdapp
-  options:
-    app:
-      namespace: argocd
-    destination:
-      server: https://kubernetes.default.svc
-      namespace: default
-    source:
-      valuefile: values.yaml
-      path: helm/[[ app ]]
-      repoURL: ${{repo-scaffolding.myapp.outputs.repoURL}}
-```
-
-Then, you can refer to these pipeline templates in the apps file.
-
----
-
-## 7 Putting It All Together
-
-Here's a complete example:
-
-```yaml
-config:
-  state:
-  backend: local
-  options:
-    stateFile: devstream.state
-
-tools:
-- name: helm-installer
-  instanceID: argocd
-
-apps:
-- name: myapp1
-  spec:
-    language: python
-    framework: django
-  repo:
-    url: github.com/ironcore864/myapp1
-  repoTemplate:
-    url: github.com/devstream-io/dtm-repo-scaffolding-python
-  ci:
-  - type: github-actions
-  cd:
-  - type: argocdapp
-```
+The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail.
diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md
index df2dda2f1..d2036b004 100644
--- a/docs/core-concepts/overview.md
+++ b/docs/core-concepts/overview.md
@@ -13,7 +13,19 @@ In essence:
 
 ---
 
-## 2 State
+## 2 Plugin
+
+Plugin is a critical concept of DevStream.
+
+As shown above, DevStream uses a core-plugin architecture where the core acts mainly as a state machine and engine. The core/engine in turn drives the plugins, which are responsible for creating/reading/updating/deleting/integrating DevOps tools.
+
+Plugins are automatically downloaded and managed by dtm according to the config file.
+
+Developers and contributors can write their own plugins to extend the capabilities of DevStream. See [creating a plugin](../development/dev/creating-a-plugin.md) for more detail.
+
+---
+
+## 3 State
 
 The _State_ records the current status of your DevOps toolchain and platform defined and created by DevStream.
 
@@ -21,15 +33,11 @@ The state contains the configuration of all the pieces and their corresponding s
 
 ---
 
-## 3 Config
+## 4 Config
 
 DevStream defines desired status of your DevOps platform in config files.
 
-The main config file, which defaults to `config.yaml` in the working directory, defines where to store the DevStream state, where to load DevStream plugins and the location of other config files.
-
-There are a few different configs, but please don't be overwhelmed because some are not mandatory, and [you can define all things within a single file](https://stackoverflow.com/questions/50788277/why-3-dashes-hyphen-in-yaml-file).
-
-Configurations in the main config contains multiple sections:
+The config can be a single YAML file, as well as a bunch of YAML files under the same directory. The config contains the following sections:
 
 - `config`: basic configuration of DevStream, at the moment mainly state-related settings. Read more [here](./state.md).
 - `vars`: variable definitions. Key/value pairs, which can be referred to in the tools/apps/pipelineTemplates sections.
@@ -39,6 +47,6 @@ Configurations in the main config contains multiple sections:
 
 ---
 
-## 4 Workflow
+## 5 Workflow
 
 ![config state resource-status workflow](../images/config_state_resource.png)
diff --git a/docs/core-concepts/state.md b/docs/core-concepts/state.md
index 1cf81af0e..e0cee5186 100644
--- a/docs/core-concepts/state.md
+++ b/docs/core-concepts/state.md
@@ -1,9 +1,50 @@
 # State
 
-We can specify which "backend" to store the DevStream state in the main config file.
+## 1 Concept
 
-A backend is where to store the state. At the moment, the following types of backends are supported:
+State records the current status of the DevOps platform defined, created and managed by DevStream. DevStream relies on the State (and config, for that matter) to calculate required actions to ensure your DevOps platform is the same as defined in the config.
+
+A `backend` is where to store the state, which we can configure in the config. At the moment, the following types of backends are supported:
 
 - local
 - k8s
 - s3
+
+## 2 How to Config the State
+
+In the `config.state` section of the config, we can define where and how to store DevStream state.
+
+### 2.1 Local File
+
+```yaml
+config:
+  state:
+    backend: local
+    options:
+      stateFile: devstream.state # optional, defaults to "devstream.state"
+```
+
+### 2.2 Kubernetes
+
+```yaml
+config:
+  state:
+    backend: k8s
+    options:
+      namespace: devstream # optional, defaults to "devstream", create if not exist
+      configmap: state     # optional, defaults to "state", create if not exist
+```
+
+### 2.3 S3
+
+```yaml
+config:
+  state:
+    backend: s3
+    options:
+      bucket: devstream-remote-state
+      region: ap-southeast-1
+      key: devstream.state
+```
+
+_Note: `options` `bucket`、`region` and `key` under the options are mandatory keys for s3 backend._
diff --git a/docs/core-concepts/tools.md b/docs/core-concepts/tools.md
index 7e6eeaa25..1c95f7c10 100644
--- a/docs/core-concepts/tools.md
+++ b/docs/core-concepts/tools.md
@@ -1,6 +1,6 @@
-# Tools and Apps
+# Tools
 
-## 1 tools
+## 1 Tools
 
 DevStream treats everything as a concept named _Tool_:
 
@@ -14,22 +14,46 @@ Each dependency is named in the format of "TOOL_NAME.INSTANCE_ID".
 
 ---
 
-## 2 apps
-
-Sometimes, you have to define multiple _Tools_ for a single app/microservice. For example, for a web application, you might need to specify the following tools:
-
-- repository scaffolding
-- continuous integration
-- continuous deployment
-
-If you have multiple apps to manage, you'd have to create many _Tools_ in the config, which can be tedious and hard to read.
-
-To manage multiple apps/microservices more easily, DevStream has another level of abstraction called _Apps_. You can define everything within one app (like the aforementioned repository scaffolding, CI, CD, etc.) with only a few config lines, making the config much easier to read and manage.
-
-Under the hood, DevStream would still convert your _Apps_ configuration into _Tools_ definition, but you do not have to worry about it.
-
----
-
-## 3 pipelineTemplates
-
-A DevStream _App_ can refer to one or multiple elements of pipelineTemplates, which are mainly CI/CD definitions. In this way, the _Apps_ definition can be shorter, sharing common CI/CD pipelines between multiple microservices.
+## 2 Configuration
+
+Define your needed `tools` in DevStream config:
+
+- `tools` is a list of `tool`.
+- Each element in the list defines a DevOps tool (managed by a DevStream plugin), with the following key/values:.
+    - `name`: a string without underscore, corresponds to the name of the plugin.
+    - `instanceID`: unique instance ID of a tool.
+    - Multiple tools defined with the same `name` or `instanceID` are allowd, but `name + instanceID` must be unique.
+- Each plugin has an optional setting `options`, and the options for each plugin is different. See the [list of plugins](../plugins/plugins-list.md) for more details.
+- Each plugin has an optional setting `dependsOn` which defines the dependencies of this plugin. E.g., if A depends on B and C, then dtm will only execute A after B and C.
+
+An example of `tools` config:
+
+```yaml
+tools:
+- name: repo-scaffolding
+  instanceID: golang-github
+  options:
+    destinationRepo:
+      owner: [[ githubUsername ]]
+      name: [[ repoName ]]
+      branch: [[ defaultBranch ]]
+      scmType: github
+    vars:
+      ImageRepo: "[[ dockerhubUsername ]]/[[ repoName ]]"
+    sourceRepo:
+      org: devstream-io
+      name: dtm-scaffolding-golang
+      scmType: github
+- name: jira-github-integ
+  instanceID: default
+  dependsOn: [ "repo-scaffolding.golang-github" ]
+  options:
+    owner: [[ githubUsername ]]
+    repo: [[ repoName ]]
+    jiraBaseUrl: https://xxx.atlassian.net
+    jiraUserEmail: foo@bar.com
+    jiraProjectKey: zzz
+    branch: main
+```
+
+`[[ githubUsername ]]`, `[[ repoName ]]` (and other variables inside the double brackets) are global variables which are defined in the `vars` section of the config.
diff --git a/docs/includes/glossary.md b/docs/includes/glossary.md
index 24ef22076..30febdf0f 100644
--- a/docs/includes/glossary.md
+++ b/docs/includes/glossary.md
@@ -1,19 +1,19 @@
-*[dtm]: Short for Devstream （Devstream 简称 dtm）
-*[Config]: TODO(introduce of config)
-*[配置]: 由一个或一组 YAML 文件组成，定义了 DevStream 需要的所有信息
-*[Plugin]: TODO(introduce of plugin)
-*[Plugins]: TODO(introduce of plugin)
-*[插件]: TODO(插件的介绍)
-*[Tool]: Each Tool corresponds to a DevStream plugin, which can either install, configure, or integrate some DevOps tools
-*[Tools]: Each Tool corresponds to a DevStream plugin, which can either install, configure, or integrate some DevOps tools
-*[工具]: 每个工具(Tool)对应了一个 DevStream 插件，它可以安装、配置或集成一些 DevOps 工具
-*[App]: TODO(introduce of app)
-*[Apps]: TODO(introduce of app)
-*[应用]: TODO(应用的介绍)
-*[PipelineTemplate]: TODO(introduce of pipelineTemplate)
-*[PipelineTemplates]: TODO(introduce of pipelineTemplate)
-*[流水线模板]: TODO(流水线模板的介绍)
-*[Output]: TODO(introduce of output)
+*[dtm]: The commandline tool of DevStream (short for DevsTreaM).
+*[Config]: A set of YAML files serving as DevStream's configuration.
+*[配置]: 由一个或一组 YAML 文件组成，定义了 DevStream 需要的所有信息。
+*[Plugin]: DevStream uses core-plugin architecture, where the core is a state machine and each plugin handles the CRUD and integration of a certain DevOps tool.
+*[Plugins]: DevStream uses core-plugin architecture, where the core is a state machine and each plugin handles the CRUD and integration of a certain DevOps tool.
+*[插件]: DevStream 使用 core-plugin 架构，core 用作状态机，插件负责管理 DevOps 工具的 CRUD。
+*[Tool]: A type of DevStream config, corresponding to a DevStream plugin, which does the CRUD and integration of a certain DevOps tool. The concept of Tool is used mainly in the context of Config.
+*[Tools]: A type of DevStream config, corresponding to a DevStream plugin, which does the CRUD and integration of a certain DevOps tool. The concept of Tool is used mainly in the context of Config.
+*[工具]: DevStream 配置的一种类型。每个工具(Tool)对应了一个 DevStream 插件，它可以安装、配置或集成一些 DevOps 工具。工具这一概念主要用在配置中。
+*[App]: A type of DevStream config, corresponding to a real-world application, for which different tools such as CI/CD can be easily configured.
+*[Apps]: A type of DevStream config, corresponding to a real-world application, for which different tools such as CI/CD can be easily configured.
+*[应用]: DevStream 配置的一种类型，对应现实中的应用程序，使用应用这种类型的配置可以简化例如 CI/CD 等工具的配置。
+*[PipelineTemplate]: A CI/CD pipeline definition which can be refered to by App.
+*[PipelineTemplates]: A CI/CD pipeline definition which can be refered to by App.
+*[流水线模板]: CI/CD 流水线的定义，可被应用所引用。
+*[Output]: Each Tool can have some Output (in the format of a key/value map), so that other tools can refer to it as their input.
 *[输出]: 每个工具(Tool)可能会有些输出，这是一个 map，可以在配置其他工具时引用
-*[State]: State records the current status of your DevOps toolchain and platform defined and created by DevStream.
+*[State]: Records the current status of your DevOps platform defined and created by DevStream.
 *[状态]: 记录了当前 DevOps 工具链的状态，包括每个工具的配置以及当下状态。