doc-site: core-concept and life-cycle explanation (#401)

* doc-site: core-concept and life-cycle explanation

* Update doc-site/docs/concepts/project-life-cycle.md

Co-authored-by: Bill Monkman <[email protected]>

* Update doc-site/docs/concepts/core-concepts.md

Co-authored-by: Bill Monkman <[email protected]>

* fixup! Update doc-site/docs/concepts/core-concepts.md

Co-authored-by: Bill Monkman <[email protected]>

Author: davidcheung

doc-site/docs/about/overview.md

@@ -70,10 +70,10 @@ Security: Properly configured access-control to resources/security groups, using
 [real-world-usage]: ./real-world-usage
 [technology-choices]: ./technology-choices
 [learning-resources]: ../reference/learning-resources
-[docs-infra]: /docs/modules/aws-eks-stack/
-[docs-backend-go]: /docs/modules/backend-go/
-[docs-backend-nodejs]: /docs/modules/backend-nodejs/
-[docs-frontend-react]: /docs/modules/frontend-react/
+[docs-infra]: https://getzero.dev/docs/modules/aws-eks-stack/
+[docs-backend-go]: https://getzero.dev/docs/modules/backend-go/
+[docs-backend-nodejs]: https://getzero.dev/docs/modules/backend-nodejs/
+[docs-frontend-react]: https://getzero.dev/docs/modules/frontend-react/
 <!-- links -->
 
 

doc-site/docs/concepts/core-concepts.md

@@ -3,3 +3,15 @@ title: Core Concepts
 sidebar_label: Core Concepts
 sidebar_position: 1
 ---
+
+## Project
+A project defines a set of **modules** to use, along with a full set of config parameters for each module which were entered by the user during the `zero init` step. These config options are stored in `zero-project.yml`.
+
+The project manifest (`zero-project.yml`) is the source of truth for the commands `create` and `apply`. It determines from where to fetch the modules, the execution order of modules, whether it will push your project to version control, module configuration, and other project information. Both staging and production environments are provisioned using the same manifest to ensure the environments are reproducible and controlled.
+
+## Module
+A module is a useful bundle of code and/or resources that can be templated out during the `create` step, then executes a provisioning flow. This could be templating out terraform infrastructure as code then provisioning the resources, or creating a backend application, making API calls to set up a build pipeline, and then deploying it.
+
+A module is defined by the **module manifest** (`zero-module.yml`) in its root folder. It contains all the parameters required to render the templated files (during `zero create`) and execute any provisioning steps, and declares it's requirements and the commands to execute during provisioning (`zero apply`).
+
+Modules can declare their dependencies, for example a backend that will be deployed can declare its dependency on the infrastructure repository so that the infrastructure will already exist by the time we want to deploy to it.

doc-site/docs/concepts/module-life-cycle.md

@@ -3,3 +3,27 @@ title: Project Life Cycle
 sidebar_label: Project Life Cycle
 sidebar_position: 2
 ---
+
+## zero init
+The goal of the `init` step is to create the project manifest (`zero-project.yml`).
+
+`zero init` will fetch each **module** defined in `zero-project.yml` from their remote repository, and prompt the user through a series of questions to fill in parameters required by each module. In this phase, the module definition will be parsed and provide defaults, options, and extra context to guide users through filling in their project details.
+
+:::note
+It's recommended to review the `zero-project.yml` and make adjustments as needed before running `zero create` and `zero apply`.
+:::
+
+## zero create
+`zero create` is run in the same folder as `zero-project.yml`. It will template out each module specified in the project manifest as the basis of your repositories, then push them to your version control repository (Github).
+
+During the `create` step, Zero will also conditionally include or exclude certain sets of files, as defined by each module. For example, it will not scaffold the authentication examples if you opted not to use this feature.
+
+## zero apply
+`zero apply` is the provisioning step that starts to make real-world changes. By default, it runs a command defined by the module to check for any dependencies, and then runs a command to actually apply any changes.
+
+### Check
+`check` is run for all the modules in your project before attempting to do the `run` step, so if a dependent's `check` fails it will not start the actual provisioning for any of the modules. This is useful to check for missing binaries or API token permissions before starting to apply any changes.
+
+### Apply
+By default, the run step is to execute `make` in the root of the module, but that can be overridden in the module definition. Run should be the one-time setup commands that allow the module to function.
+For example, in the infrastructure repository, this would be to **run terraform**, and for the backend repository, this could be to  **make API calls to CircleCI to set up your build pipeline**.

doc-site/docs/concepts/project-life-cycle.md

@@ -12,14 +12,14 @@ module.exports = {
         type: 'autogenerated',
         dirName: 'getting-started',
       }],
-      "Reference": [{
-        type: 'autogenerated',
-        dirName: 'reference',
-      }],
       "Concepts": [{
         type: 'autogenerated',
         dirName: 'concepts',
       }],
+      "Reference": [{
+        type: 'autogenerated',
+        dirName: 'reference',
+      }],
     },
     sidebarsNavModules(config),
   ]