devstream-io · daniel-hutao · Apr 21, 2022 · Apr 21, 2022
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -67,8 +67,8 @@ Both "body" and "footer" are optional; BREAKING CHANGE can be addressed both in
 
 ### Creating a New Plugin
 
-See [creating_a_plugin.md](./docs/creating_a_plugin.md).
+See our [doc about creating a plugin here](https://www.devstream.io/docs/creating-a-plugin).
 
 ## Development Workflow
 
-See [development_workflow](./docs/development_workflow.md).
+See [development workflow documentation here](https://www.devstream.io/docs/development-workflow).
diff --git a/README.md b/README.md
@@ -51,6 +51,16 @@ DevStream aims to be the package manager for DevOps tools.
 
 To be more ambitious, DevStream wants to be the Linux kernel, around which different distros can be created with various components so that you can always have the best components for each part of your SDLC workflow.
 
+## Why `dtm`?
+
+Q: The CLI tool is named `dtm`, while the tool itself is called DevStream. What the heck?! Where is the consistency?
+
+A: Inspired by [`git`](https://github.com/git/git#readme), the name is (depending on your mood):
+
+- a symmetric, scientific acronym of **d**evs**t**rea**m**.
+- "devops toolchain manager": you're in a good mood, and it actually works for you.
+- "dead to me": when it breaks.
+
 ## Why Use DevStream?
 
 No more manual curl/wget download, apt install, helm install; no more local experiments and playing around just to get a piece of tool installed correctly.
@@ -61,48 +71,14 @@ Want to install another different tool for a try? No problem.
 
 Want to remove or reinstall a specific piece in the workflow? DevStream has got your back!
 
-## Supported DevOps Tools
-
-| Type                   | Plugin                         | Note                           | Usage/Doc |
-|------------------------|--------------------------------|--------------------------------|-----------|
-| Issue Tracking         | trello-github-integ            | Trello/GitHub integration      | [doc](./docs/plugins/trello-github-integ.md) |
-| Source Code Management | github-repo-scaffolding-golang | Go WebApp scaffolding          | [doc](./docs/plugins/github-repo-scaffolding-golang.md) |
-| CI                     | jenkins                        | Jenkins installation           | [doc](./docs/plugins/jenkins.md) |
-| CI                     | githubactions-golang           | GitHub Actions CI for Golang   | [doc](./docs/plugins/githubactions-golang.md)          |
-| CI                     | githubactions-python           | GitHub Actions CI for Python   | [doc](./docs/plugins/githubactions-python.md)          |
-| CI                     | githubactions-nodejs           | GitHub Actions CI for Nodejs   | [doc](./docs/plugins/githubactions-nodejs.md)          |
-| CI                     | gitlabci-golang                | GitLab CI for Golang           | [doc](./docs/plugins/gitlabci-golang.md)          |
-| CD/GitOps              | argocd                         | ArgoCD installation            | [doc](./docs/plugins/argocd.md)          |
-| CD/GitOps              | argocdapp                      | ArgoCD Application creation    | [doc](./docs/plugins/argocdapp.md)          |
-| Monitoring             | kube-prometheus                | Prometheus/Grafana K8s install | [doc](./docs/plugins/kube-prometheus.md)          |
-| Observability          | devlake                        | DevLake installation           | [doc](./docs/plugins/devlake.md)          |
-| LDAP                   | openldap                       | OpenLDAP installation          | [doc](./docs/plugins/openldap.md)          |
-
 ## Installation
 
-### macOS
-
-Install `dtm` via [Homebrew](https://brew.sh/):
-
-1. Add DevStream's tap to Homebrew: `brew tap devstream-io/devstream`
-2. Install `dtm`: `brew install devstream-io/devstream/dtm`
+Please visit GitHub [Releases](https://github.com/devstream-io/devstream/releases) page and download the appropriate binary according to your operating system and architecture.
 
 ## Quick Start
 
 If you want to get a quick start, follow our [quick start](./docs/quickstart_en.md) doc now.
 
-## Best Practices Toolchain Integration
-
-DevStream supports the management of many tools. You can flexibly combine some tools to meet the DevOps toolchain your need.
-
-And yes, if you ask me if any recommended practices that can be used out of the box,
-
-I am happy to tell you that we have, and we are constantly adding more possible combinations,
-
-so you are more than welcome to tell us what combinations you expect.
-
-- [GitOps Toolchain](docs/best_practices/gitops.md)
-
 ## Configuration
 
 This is an example of DevStream config: [examples/quickstart.yaml](./examples/quickstart.yaml).
@@ -111,84 +87,90 @@ Remember to open this configuration file, modify all FULL_UPPER_CASE_STRINGS (li
 
 Pay attention to the meaning of each item to ensure that it is what you want.
 
-For other plugins, checkout the [docs/plugins](./docs/plugins/) folder for detailed usage in their documentations.
+For other plugins, checkout the "Plugins" section in our [doc](https://www.devstream.io/docs/index) for detailed usage.
 
-## Run
+## Usage
 
 To apply the config, run:
 
-```bash
+```shell
 ./dtm apply -f YOUR_CONFIG_FILE.yaml
 ```
 
 If you don't specify the config file with the "-f" parameter, it will try to use the default value which is "config.yaml" from the current directory.
 
-_`dtm` will compare the config, the state, and the resources to decide whether a "create", "update", or "delete" is needed. For more information, see [this document here](./docs/config_state_resource_explanation.md)._
+_`dtm` will compare the config, the state, and the resources to decide whether a "create", "update", or "delete" is needed. For more information, read our [Core Concepts documentation here](https://www.devstream.io/docs/core-concepts)._
 
 The command above will ask you for confirmation before actually executing the changes. To apply without confirmation (like `apt-get -y update`), run:
 
-```bash
+```shell
 ./dtm -y apply -f YOUR_CONFIG_FILE.yaml
 ```
 
 To delete everything defined in the config, run:
 
-```bash
+```shell
 ./dtm delete -f YOUR_CONFIG_FILE.yaml
 ```
 
 _Note that this deletes everything defined in the config. If some config is deleted after apply (state has it but config not), `dtm delete` won't delete it. It differs from `dtm destroy`._
 
 Similarly, to delete without confirmation:
 
-```bash
+```shell
 ./dtm -y delete -f YOUR_CONFIG_FILE.yaml
 ```
 To delete everything defined in the config, regardless of the state:
 
-```bash
+```shell
 ./dtm delete --force -f YOUR_CONFIG_FILE.yaml
 ```
 
 To verify, run:
 
-```bash
+```shell
 ./dtm verify -f YOUR_CONFIG_FILE.yaml
 ```
 
 To destroy everything, run:
 
-```bash
+```shell
 ./dtm destroy
 ```
 
 _`dtm` will read the state, then determine which tools are installed, and then remove those tools. It's same as `dtm apply -f empty.yaml` (empty.yaml is an empty config file)._
 
-## Dev Info
+## Best Practices Toolchain Integration
+
+DevStream supports the management of many tools. You can flexibly combine some tools to meet the DevOps toolchain your need.
 
-### Source
+And yes, if you ask me if any recommended practices that can be used out of the box,
 
-#### Prerequisite Tools
+I am happy to tell you that we have, and we are constantly adding more possible combinations,
 
-- Git
-- Go (1.17+)
+so you are more than welcome to tell us what combinations you expect.
 
-#### Fetch from GitHub
+- [GitOps Toolchain](https://www.devstream.io/docs/best-practices/gitops)
 
-```bash
-mkdir -p ~/gocode
-cd ~/gocode
-git clone https://github.com/devstream-io/devstream.git
-```
+## Supported DevOps Tools
 
-#### Build
+DevStream already supports many tools and it's still growing. For a complete list of supported tools, check out our [list of plugins](https://www.devstream.io/docs/plugins/plugins-list) document.
 
-To do a multi-threaded build, run:
+Alternatively, run `dtm list plugins` and it will show you all the available plugins.
 
-```bash
-cd ~/gocode/stream
+## Dev Info
+
+### Pre-requisites
+
+- Git
+- Go (1.17+)
+
+### Build
+
+```shell
+cd path/to/devstream
 make clean
-make build -j8
+make build -j8 # multi-threaded build
 ```
 
 This builds everything: `dtm` and all the plugins.
@@ -200,41 +182,23 @@ We also support the following build modes:
 
 See `make help` for more information.
 
-#### Test
+### Test
 
-Run unit tests:
+Run all unit tests:
 
-```bash
+```shell
 go test ./...
 ```
 
-Run e2e tests:
-
-```bash
-make e2e
-```
-
-## Architecture
-
-See [docs/architecture.md](./docs/architecture.md).
-
-## Why `dtm`?
-
-Q: The CLI tool is named `dtm`, while the tool itself is called DevStream. What the heck?! Where is the consistency?
+e2e test runs on GitHub actions.
 
-A: Inspired by [`git`](https://github.com/git/git#readme), the name is (depending on your mood):
+## Contribute
 
-- a symmetric, scientific acronym of **d**evs**t**rea**m**.
-- "devops toolchain manager": you're in a good mood, and it actually works for you.
-- "dead to me": when it breaks.
+First of all, thanks for wanting to contribute to DevStream! For more details on how to contribute, contributor growth program, style guide and more, please check out our [CONTRIBUTING](./CONTRIBUTING.md) document.
 
 ## Community
 
 We will regularly organize `DevStream Community Meeting`, please visit the [wiki](https://github.com/devstream-io/devstream/wiki) page for details.
 
 - Message us on <a href="https://join.slack.com/t/devstream-io/shared_invite/zt-16tb0iwzr-krcFGYRN7~Vv1suGZjdv4w" target="_blank">Slack.</a>
 - For Chinese users, the WeChat group QR code can be obtained from [here](docs/README_zh.md).
-
-## Contribute
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,121 @@
+# Documentation
+
+Our docs website is: https://www.devstream.io/docs/index. Read more there.
+
+---
+
+To report a bug or create a new doc, please go to this repo: https://github.com/devstream-io/website.
+
+If you want to know exactly how, read on:
+
+## Creating a New Documentation (English)
+
+First of all, thanks for your effort in improving our documentation!
+
+To create a new document, please do the followings:
+
+### 1 Fork the Website Repo
+
+Fork this repo: https://github.com/devstream-io/website.
+
+### 2 Creating a New Markdown File
+
+In the forked repo, under `docs` folder, create a new Markdown file.
+
+_Note 1: We use number-indexed filenames so that it's easier to understand the order without having to look inside each doc._
+
+ For example:
+
+```shell
+.
+├── 01-index.md
+├── 02-quickstart.md
+├── 03-config.md
+├── 04-architecture.md
+├── 05-core-concepts.md
+├── 06-output.md
+├── 07-commands-explained.md
+├── 08-plugins
+├── 09-development-workflow.md
+├── 10-project-layout.md
+├── 11-creating-a-plugin.md
+├── 12-best-practices
+└── 13-autocomplete.md
+```
+
+If you want to insert a new doc at a certain position, you need to rename those files after it.
+
+_Note 2: in each file, at the very beginning, we have a section like the following:_
+
+```yaml
+---
+sidebar_position: 1
+---
+```
+
+This number corresponds to the number index of the file.
+
+Then you can simply write the documentation in Markdown format. 
+
+If you need to insert a picture, the picture should be put under `static/img/docs/`. Refer to existing documents about how to use links to an image file under the static folder.
+
+### 3 i18n
+
+Currently, our doc supports English and Simplified Chinese. English doc is our top priority. For Simplified Chinese, we can put the English doc there without translation.
+
+For example, if you want to create a Simplified Chinese version of the doc `docs/01-index.md`, you can copy it to the folder for Simplified Chinese:
+
+```shell
+cp docs/01-index.md i18n/zh/docusaurus-plugin-content-docs/current/
+```
+
+Then open the file `i18n/zh/docusaurus-plugin-content-docs/current`, and update the content to Simplified Chinese.
+
+### 4 Create a Pull Request to `devstream-io/website`
+
+---
+
+## 创建一个中文文档
+
+我们的文档以英文为最高优先级，但如果您只想写一份中文文档（并且也不想把它翻译成英文），您可以这样做：
+
+### 1 Fork the Website Repo
+
+Fork我们的文档所在的repo: https://github.com/devstream-io/website.
+
+### 2 创建一个新的Markdown文件
+
+在fork的repo里，在`i18n/zh/docusaurus-plugin-content-docs/current`目录下，
+创建一个新的Markdown文件。
+
+_注1: 文件名以数字编号打头，以便我们不用打开文档站也能一眼看出某篇文档的顺序和位置。_
+
+_注2: 在每个文档里最开头部分我们有一段类似于下面的指令：_
+
+```yaml
+---
+sidebar_position: 1
+---
+```
+
+这个`sidebar_position`的数字要跟文件名开头的数字一致。
+
+如果你想把你的文件插入在某个特定的位置，你需要让你新创建的文件名和里面的sidebar_position保持一致，并且修改后续的文件。
+
+如果您需要在文档中插入图片，图片请放在`static/img/docs/`目录下。可以参考已有的文档来学习如何引用这个目录下的图片。
+
+### 3 英文文档需要翻译吗？
+
+不需要，但需要放一个占位符。
+
+比如，如果您先创建了`i18n/zh/docusaurus-plugin-content-docs/current/01-index.md`文档，那么请把它复制到英文文档所在的目录下：
+
+```shell
+cp i18n/zh/docusaurus-plugin-content-docs/current/ docs/01-index.md
+```
+
+然后编辑`docs/01-index.md`文件，删掉英文内容，写一个"Work in Progress"即可，这样DevStream PMC成员就知道这个文档是需要被翻译的了。
+
+### 4 提交PR
+
+您的成果需要以PR的形式提交至devstream-io/website repo.