Merge pull request #1300 from garden-io/docs-restructure

docs: restructure and add new basic guides

README.md

@@ -20,17 +20,17 @@
 - Spin up your whole stack with a single command, and (optionally) watch for changes. Only what’s needed gets re-built, re-deployed, and/or re-tested, so you get a **much faster feedback loop**.
 - **Shared development clusters with fast in-cluster building and image caching for Kubernetes.** This allows teams to easily share build and test results, and for CI to become much faster because it can use the same build and test caches as the team.
 - Get helpful information when your deployments fail. Garden collects events and logs and displays them prominently when issues come up, and strives to "fail fast", so that you don't need to wait for timeouts or dive into kubectl whenever something is wrong.
-- Easily write [integration test suites](https://docs.garden.io/using-garden/development-workflows#tests-and-dependencies) that have runtime dependencies. Run tests *before* pushing your code to CI, and avoid having to mock or stub your own services.
+- Easily write [integration test suites](https://docs.garden.io/guides/development-workflows#tests-and-dependencies) that have runtime dependencies. Run tests *before* pushing your code to CI, and avoid having to mock or stub your own services.
 - Define [tasks](https://github.com/garden-io/garden/tree/v0.10.14/examples/tasks) that run as part of your deployment process—e.g. database migrations or scaffolding.
-- [Hot reload](https://docs.garden.io/using-garden/hot-reload) lets you near-instantaneously update code and static files in containers as they run, for services that support in-place reloading.
-- [Remote sources](https://docs.garden.io/using-garden) support allows your project to automatically pull code from different repositories.
+- [Hot reload](https://docs.garden.io/guides/hot-reload) lets you near-instantaneously update code and static files in containers as they run, for services that support in-place reloading.
+- [Remote sources](https://docs.garden.io/guides/using-remote-sources) support allows your project to automatically pull code from different repositories.
 - The built-in web **dashboard** gives you a full overview of your stack (and many more UI features are planned to further aid with development).
-- Build, test and deploy Docker containers, [Helm charts](https://docs.garden.io/using-garden/using-helm-charts), OpenFaaS functions and more.
+- Build, test and deploy Docker containers, [Helm charts](https://docs.garden.io/guides/using-helm-charts), OpenFaaS functions and more.
 - An extensible plug-in system ensures you’ll later be able add anything that’s not on the above list, or create custom module types tailored to your needs (*due summer 2019*).
 
 ## Installation
 
-*(Check out our documentation for more [detailed instructions](https://docs.garden.io/basics/installation))*
+*(Check out our documentation for more [detailed instructions](https://docs.garden.io/installation))*
 
 ### macOS
 
@@ -96,8 +96,8 @@ You can find Garden’s full documentation at [https://docs.garden.io](https://d
 
 Overview:
 
-- [Basics](https://docs.garden.io/basics)—installation instructions, our quick start guide, and an overview of the main concepts around Garden.
-- [Using Garden](https://docs.garden.io/using-garden)—development workflows, Garden configuration files, usage with remote Kubernetes clusters, and setting up hot reload.
+- [Using Garden](https://docs.garden.io/basics)—short Guides on incrementally adding the main Garden constructs to your project.
+- [Guides](https://docs.garden.io/guides)—development workflows, Garden configuration files, usage with remote Kubernetes clusters, and setting up hot reload.
 - [Example Projects](https://docs.garden.io/examples)—guides based on some of the [examples](https://github.com/garden-io/garden/tree/v0.10.14/examples).
 - [Reference](https://docs.garden.io/reference)—glossary, commands reference, configuration files reference, and template strings reference.
 - [FAQs](https://docs.garden.io/#faqs).
@@ -108,7 +108,7 @@ The [examples](https://github.com/garden-io/garden/tree/v0.10.14/examples) folde
 
 Garden runs as a developer tool on your machine or in CI, that looks at your source code and configuration files, runs tests, and resolves your changes to update your development environment. Garden can watch your files and run continuously, or you can trigger it manually via the CLI.
 
-For configuration, Garden is centered around the **[Stack Graph](https://docs.garden.io/basics/stack-graph)**, which allows you to fully codify how each part of your stack is built, deployed and tested—making your workflow reproducible and portable.
+For configuration, Garden is centered around the **[Stack Graph](https://docs.garden.io/stack-graph)**, which allows you to fully codify how each part of your stack is built, deployed and tested—making your workflow reproducible and portable.
 
 <p align="center">
   <img src="docs/stack-graph.png" width="50%">

docs/README.md

@@ -1,30 +1,35 @@
 # Table of Contents
 
-* [Basics](./basics/README.md)
-  * [Installation](./basics/installation.md)
-  * [Quick Start](./basics/quick-start.md)
-  * [Stack Graph](./basics/stack-graph.md)
+* [Installation](./installation.md)
+* [Quick Start](./quick-start.md)
+* [Stack Graph](./stack-graph.md)
 * [Using Garden](./using-garden/README.md)
-  * [Cloud Provider Set-up](./using-garden/cloud-provider-setup.md)
-  * [Configuration Files](./using-garden/configuration-files.md)
-  * [Container Modules](./using-garden/container-modules.md)
-  * [Development Workflows](./using-garden/development-workflows.md)
-  * [Helm Charts](./using-garden/using-helm-charts.md)
-  * [Hot Reload](./using-garden/hot-reload.md)
-  * [In-Cluster Building](./using-garden/in-cluster-building.md)
-  * [Local Kubernetes](./using-garden/local-kubernetes.md)
-  * [Remote Kubernetes](./using-garden/remote-kubernetes.md)
-  * [Remote Sources](./using-garden/using-remote-sources.md)
-  * [Terraform](./using-garden/terraform.md)
-  * [Variables and templating](./using-garden/variables-and-templating.md)
+  * [Creating a Project](./using-garden/creating-a-project.md)
+  * [Adding Modules](./using-garden/adding-modules.md)
+  * [Adding Services](./using-garden/adding-services.md)
+  * [Running Tests](./using-garden/running-tests.md)
+  * [Running Tasks](./using-garden/running-tasks.md)
+* [Guides](./guides/README.md)
+  * [Cloud Provider Set-up](./guides/cloud-provider-setup.md)
+  * [Configuration Files](./guides/configuration-files.md)
+  * [Container Modules](./guides/container-modules.md)
+  * [Development Workflows](./guides/development-workflows.md)
+  * [Helm Charts](./guides/using-helm-charts.md)
+  * [Hot Reload](./guides/hot-reload.md)
+  * [In-Cluster Building](./guides/in-cluster-building.md)
+  * [Local Kubernetes](./guides/local-kubernetes.md)
+  * [Remote Kubernetes](./guides/remote-kubernetes.md)
+  * [Remote Sources](./guides/using-remote-sources.md)
+  * [Terraform](./guides/terraform.md)
+  * [Variables and templating](./guides/variables-and-templating.md)
 * [Example Projects](./examples/README.md)
   * [Demo Project](./examples/demo-project.md)
   * [TLS Project](./examples/tls-project.md)
   * [Using Garden in CI](./examples/using-garden-in-ci.md)
 * [Reference](./reference/README.md)
+  * [Glossary](./reference/glossary.md)
   * [Commands Reference](./reference/commands.md)
   * [Config Files Reference](./reference/config.md)
-  * [Glossary](./reference/glossary.md)
   * [Module Types](./reference/module-types/README.md)
     * [Container](./reference/module-types/container.md)
     * [Exec](./reference/module-types/exec.md)

docs/examples/README.md

@@ -1,5 +1,6 @@
 ---
-order: 3
+order: 6
+title: Example Projects
 ---
 # Example Projects
 
@@ -9,7 +10,7 @@ Here we see how to "gardenify" a pre-existing project, creating a project config
 
 ## [Using Garden in CI](./using-garden-in-ci.md)
 
-In this example we demonstrate how to use Garden in a CI pipeline to run tests and deploy to preview and staging environments. Note that you'll need to have a [remote Kubernetes cluster](../using-garden/remote-kubernetes.md) set up to complete the steps in the guide.
+In this example we demonstrate how to use Garden in a CI pipeline to run tests and deploy to preview and staging environments. Note that you'll need to have a [remote Kubernetes cluster](../guides/remote-kubernetes.md) set up to complete the steps in the guide.
 
 ## [TLS project](./tls-project.md)
 

docs/examples/demo-project.md

@@ -13,7 +13,7 @@ In what follows you'll learn how to:
 
 ## Before you get started
 
-This tutorial assumes that you already have a running [installation of Garden](../basics/installation.md).
+This tutorial assumes that you already have a running [installation of Garden](../installation.md).
 
 ## Clone the example repo
 
@@ -53,7 +53,7 @@ The task at hand is to configure these services so that they can run on the Gard
 
 ## Project-wide configuration
 
-To begin with, every project needs a project-wide `garden.yml` [configuration file](../using-garden/configuration-files.md) at the root level. There we define, among other things, the name of the project, and the [providers](../reference/glossary.md#Provider) the project requires.
+To begin with, every project needs a project-wide `garden.yml` [configuration file](../guides/configuration-files.md) at the root level. There we define, among other things, the name of the project, and the [providers](../reference/glossary.md#Provider) the project requires.
 
 Let's go ahead and create one:
 
@@ -76,7 +76,7 @@ Above, we've specified the name of our project and configured it to use the `loc
 
 ## Module configuration
 
-Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../basics/stack-graph.md#structure-and-terminology).
+Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../stack-graph.md#structure-and-terminology).
 
 We'll start with the module for the `frontend`:
 
@@ -134,7 +134,7 @@ services:
         port: http
 ```
 
-The [services](../using-garden/configuration-files.md#Services) field is specific to container modules, and defines the services exposed by the module. In this case, our containerized Node.js server. The other keys tell Garden how to expose our `/hello-frontend` endpoint.
+The [services](../guides/configuration-files.md#Services) field is specific to container modules, and defines the services exposed by the module. In this case, our containerized Node.js server. The other keys tell Garden how to expose our `/hello-frontend` endpoint.
 
 ## Deploying
 

docs/examples/using-garden-in-ci.md

@@ -5,7 +5,7 @@ In this guide we'll demonstrate how Garden can fit into your continuous integrat
 * Use the same tool and the same set of commands for the entire development cycle, from source to finish.
 * No need to change your CI configuration when you change your stack since Garden holds the entire stack graph.
 * The only thing you need to install in CI is the Garden CLI and its dependencies (or use a ready-made Garden container image).
-* When using [in-cluster building](../using-garden/in-cluster-building.md) your CI also uses the same build and test result cache as you and your team, which makes for a much faster pipeline.
+* When using [in-cluster building](../guides/in-cluster-building.md) your CI also uses the same build and test result cache as you and your team, which makes for a much faster pipeline.
 
 To use Garden in your CI pipeline you need the following:
 
@@ -14,7 +14,7 @@ To use Garden in your CI pipeline you need the following:
 
 For the purposes of this example we'll be using [CircleCI](https://circleci.com) and deploying to a Google Kubernetes Engine (GKE) cluster. However, the instructions below can easily be applied to other CI platforms and cloud providers.
 
-The guide is based on the [Remote Kubernetes](https://docs.garden.io/using-garden/remote-kubernetes) example. In what follows we assume that you've read that guide and that you have a running Kubernetes cluster to work with.
+The guide is based on the [Remote Kubernetes](https://docs.garden.io/guides/remote-kubernetes) example. In what follows we assume that you've read that guide and that you have a running Kubernetes cluster to work with.
 
 ## Prerequisites
 
@@ -31,7 +31,7 @@ To see it in action, you can fork the repository and follow the set-up steps bel
 
 ## Configure remote environments
 
-Configuring Garden to work against a remote Kubernetes cluster is explained step by step in our [Remote Kubernetes guide](../using-garden/remote-kubernetes.md). For this example, we also use [in-cluster building](../using-garden/in-cluster-building.md).
+Configuring Garden to work against a remote Kubernetes cluster is explained step by step in our [Remote Kubernetes guide](../guides/remote-kubernetes.md). For this example, we also use [in-cluster building](../guides/in-cluster-building.md).
 
 For this project we're using three environments: `local`, `preview` and `staging`. The `local` environment is the default and is configured for a local Kubernetes cluster that runs on the user's machine. The other two run on remote clusters.
 

docs/guides/README.md

@@ -0,0 +1,54 @@
+---
+order: 5
+title: Guides
+---
+
+# Guides
+
+## [Development Workflows](./development-workflows.md)
+
+In this article we discuss how to set up a new Garden project, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies.
+
+## [Configuration Files](./configuration-files.md)
+
+This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests.
+
+## [Container Modules](./container-modules.md)
+
+One of the most commonly used module types for Garden is the `container` module type. This guide walks through its usage and configuration.
+
+## [Local Kubernetes](./local-kubernetes.md)
+
+Garden works great with local Kubernetes setups. Here you'll find installation and usage instructions for some
+common flavors of local Kubernetes setups, such as Minikube, Docker for Desktop and MicroK8s.
+
+## [Remote Kubernetes](./remote-kubernetes.md)
+
+Garden can also work smoothly with remote Kubernetes clusters. If you'd like to use a remote cluster, you may have some
+additional considerations and requirements. Take a look at this guide for details.
+
+## [In-cluster Building](./in-cluster-building.md)
+
+One of Garden's most powerful features is the ability to build images in your Kubernetes development cluster, thus
+avoiding the need for local Kubernetes clusters. This guide covers the requirements for in-cluster building and how
+to set it up.
+
+## [Cloud Provider Set-up](./cloud-provider-setup.md)
+
+Instructions for creating and configuring Kubernetes clusters with GKE (Google), AKS (Azure), EKS and kops (AWS), and how to connect to them with Garden.
+
+## [Using Helm charts](./using-helm-charts.md)
+
+The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts.
+
+## [Using Remote Sources](./using-remote-sources.md)
+
+Instructions for how to import code from remote repositories into a Garden project.
+
+## [Hot Reload](./hot-reload.md)
+
+This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers.
+
+## [Terraform](./terraform.md)
+
+This article discusses how to use the Terraform provider, for provisioning infrastructure as part of your Garden project.

docs/using-garden/configuration-files.md → docs/guides/configuration-files.md

@@ -1,7 +1,7 @@
 # Configuration Files
 
 Garden is configured via `garden.yml` configuration files, which Garden collects and compiles into a
-[Stack Graph](../basics/stack-graph.md) of your project.
+[Stack Graph](../stack-graph.md) of your project.
 
 The [project-wide](#project-configuration) `garden.yml` file should be located in the top-level directory of the
 project's Git repository.

docs/using-garden/development-workflows.md → docs/guides/development-workflows.md

@@ -1,7 +1,7 @@
 # Development Workflows
 
-Now that you've had a glimpse of the basic Garden commands in the [Quick Start](../basics/quick-start.md) guide, and
-learned about the [Stack Graph](../basics/stack-graph.md), let's go through some typical Garden workflows.
+Now that you've had a glimpse of the basic Garden commands in the [Quick Start](../quick-start.md) guide, and
+learned about the [Stack Graph](../stack-graph.md), let's go through some typical Garden workflows.
 
 We'll keep using the [Demo Project](../examples/demo-project.md) example, but the same principles will apply for most
 Garden projects.

docs/using-garden/local-kubernetes.md → docs/guides/local-kubernetes.md

@@ -74,4 +74,4 @@ If you happen to have installed both Minikube and a version of Docker for Mac wi
 is set as the current context, the first available context is used.
 
 (If you're not yet familiar with Garden configuration files, see:
-[Configuration files](../using-garden/configuration-files.md))
+[Configuration files](../guides/configuration-files.md))