Merge pull request #54 from slack/structure

Tweak structure to accommodate reader flow

Author: slack

mkdocs.yml

@@ -5,9 +5,10 @@
 site_name: Deis Documentation
 pages:
   - Welcome: index.md
+  - Quick Start: installing-deis/quickstart.md
   - Understanding Deis:
-    - Architecture: understanding-deis/architecture.md
     - Concepts: understanding-deis/concepts.md
+    - Architecture: understanding-deis/architecture.md
     - Components: understanding-deis/components.md
   - Installing Deis:
     - Quick Start: installing-deis/quickstart.md

src/index.md

@@ -2,9 +2,9 @@
 
 Deis (pronounced DAY-iss) Workflow is an open source Platform as a Service (PaaS) that adds a developer-friendly layer to any Kubernetes cluster, making it easy to deploy and manage applications on your own servers.  It includes capabilities for building and deploying from source via git push, configuring your applications, managing and rolling back releases, managing application domain names and SSL certificates, edge routing, application log aggregation, and managing access to application resources.  All of this is exposed through a simple REST API and command line interface.
 
-To get started with Workflow, follow our [Quick Start][quickstart] guide.
+For more detailed information about Workflow view the [Concepts][concepts] and [Architecture][arch] sections.
 
-For more detailed information about Workflow view the [Architecture][arch] and [Concepts][concepts] sections.
+To get started with Workflow, follow our [Quick Start][quickstart] guide.
 
 [arch]: understanding-deis/architecture.md
 [concepts]: understanding-deis/concepts.md

src/installing-deis/quickstart.md

@@ -29,10 +29,14 @@ See [Configuring DNS][] for more information on properly setting up your DNS rec
 Once your cluster has been provisioned and Deis Workflow has been installed, you can
 [install the client][client] and [register your first user][register]!
 
+## Deploy your first Application
+
+Last but not least, select your build process and [deploy your first application][deploy].
 
 [client]: ../using-deis/installing-the-client.md
 [configuring object storage]: configuring-object-storage.md
 [configuring dns]: ../managing-deis/configuring-dns.md
+[deploy]: ../using-deis/deploying-an-application.md
 [install deis]: installing-deis-workflow.md
 [register]: ../using-deis/registering-a-user.md
 [system requirements]: system-requirements.md

src/understanding-deis/components.md

@@ -12,7 +12,7 @@ the functionality in your own project we invite you to give it a shot!
 
 ## Controller
 
-Project Location: [deis/workflow](https://github.com/deis/workflow)
+**Project Location:** [deis/workflow](https://github.com/deis/workflow)
 
 The controller component is an HTTP API server which serves as the endpoint for
 the `deis` CLI. The controller provides all of the platform functionality as
@@ -21,7 +21,7 @@ of its data to the database component.
 
 ## Database
 
-Project Location: [deis/postgres](https://github.com/deis/postgres)
+**Project Location:** [deis/postgres](https://github.com/deis/postgres)
 
 The database component is a managed instance of [PostgreSQL][] which holds a
 majority of the platforms state. Backups and WAL files are pushed to the object
@@ -32,7 +32,7 @@ and restore read the documentation for
 
 ## <a name="builder"></a>Builder: builder, slugbuilder, and dockerbuilder
 
-Project Location: [deis/builder](https://github.com/deis/builder)
+**Project Location:** [deis/builder](https://github.com/deis/builder)
 
 
 The builder component is responsible for accepting code pushes via [Git][] and
@@ -46,7 +46,7 @@ managing the build process of your [Application][]. The builder process is:
 
 Builder currently supports both buildpack and Dockerfile based builds.
 
-Project Location: [deis/slugbuilder](https://github.com/deis/slugbuilder)
+**Project Location:** [deis/slugbuilder](https://github.com/deis/slugbuilder)
 
 For Buildpack-based deploys, the builder component will launch a one-shot Pod
 in the `deis` namespace. This pod runs `slugbuilder` component which handles
@@ -56,7 +56,7 @@ its depdencies as determined by the buildpack. The slug is pushed to the
 cluster-configured object storage for later execution. For more information
 about buildpacks see [using buildpacks][using-buildpacks].
 
-Project Location: [deis/dockerbuilder](https://github.com/deis/dockerbuilder)
+**Project Location:** [deis/dockerbuilder](https://github.com/deis/dockerbuilder)
 
 For Applications which contain a `Dockerfile` in the root of the repository,
 `builder` will instead launch the `dockerbuilder` to package your application.
@@ -66,7 +66,7 @@ Docker registry on cluster. For more information see [using Dockerfiles][using-d
 
 ## Slugrunner
 
-Project Location: [deis/slugrunner](https://github.com/deis/slugrunner)
+**Project Location:** [deis/slugrunner](https://github.com/deis/slugrunner)
 
 Slugrunner is the component responsible for executing buildpack-based
 Applications. Slugrunner receives slug information from the controller and
@@ -75,7 +75,7 @@ processes.
 
 ## Object Storage
 
-Project Location: [deis/minio](https://github.com/deis/mino)
+**Project Location:** [deis/minio](https://github.com/deis/mino)
 
 All of the Workflow components ship their persistent data to cluster configured
 S3 compatibile Object Storage. For example, database ships its WAL files,
@@ -92,7 +92,7 @@ configure minio to use persistent storage available in your environment.
 
 ## Registry
 
-Project Location: [deis/registry](https://github.com/deis/registry)
+**Project Location:** [deis/registry](https://github.com/deis/registry)
 
 The registry component is a managed docker registry which holds application
 images generated from the builder component. Registry persists the Docker image
@@ -101,7 +101,7 @@ configured for the cluster.
 
 ## Router
 
-Project Location: [deis/router](https://github.com/deis/router)
+**Project Location:** [deis/router](https://github.com/deis/router)
 
 The router component is based on [Nginx][] and is responsible for routing
 inbound HTTP(S) traffic to your applications. The default workflow charts
@@ -118,20 +118,26 @@ configuration view the router [project documentation][router-documentation].
 The logging subystem consists of two compoents. Fluentd handles log shipping
 and logger maintains a ring-buffer of application logs.
 
-Project Location: [deis/fluentd](https://github.com/deis/fluentd)
+
+**Project Location:** [deis/fluentd](https://github.com/deis/fluentd)
 
 Fluentd is deployed to your Kubernetes cluster via Daemon Sets. Fluentd
 subscribes to all container logs, decorates the output with Kubernetes metadata
 and can be configured to drain logs to multiple destinations. By default,
 fluentd ships logs to the logger component, which powers `deis logs`.
 
-Project Location: [deis/logger](https://github.com/deis/logger)
+**Project Location:** [deis/logger](https://github.com/deis/logger)
 
 The `logger` compoent receives log streams from `fluentd`, collating by
 Application name. Logger does not persist logs to disk, instead maintaining an
 in-memory ring buffer. For more information on logger see the [project
 documentation][logger-documentation].
 
+## See Also
+
+* [Workflow Concepts][concepts]
+* [Workflow Components][components]
+
 [Application]: ../reference-guide/terms.md#application
 [Config]: ../reference-guide/terms.md#config
 [Git]: http://git-scm.com/
@@ -140,6 +146,8 @@ documentation][logger-documentation].
 [WAL-E]: https://github.com/wal-e/wal-e
 [architecture]: architecture.md
 [backupandrestore]: ../managing-deis/backing-up-and-restoring-data.md
+[components]: components.md
+[concepts]: concepts.md
 [configure-objectstorage]: ../installing-deis/configuring-object-storage.md
 [logger-documentation]: https://github.com/deis/logger
 [release]: ../reference-guide/terms.md#release

src/understanding-deis/concepts.md

@@ -118,14 +118,15 @@ to external or third-party vendor services.
 
 ## See Also
 
-* [Architecture](architecture.md)
-* [Twelve-Factor App][]
+* [Workflow Architecture][architecture]
+* [Workflow Components][components]
 
 [Build and Run]: http://12factor.net/build-release-run
 [Docker]: https://www.docker.com/
 [Kubernetes]: https://kubernetes.io
 [Twelve-Factor App]: http://12factor.net/
 [application]: ../reference-guide/terms.md#application
+[architecture]: architecture.md
 [backing services]: http://12factor.net/backing-services
 [build]: ../reference-guide/terms.md#build
 [builder]: components.md#builder

src/using-deis/deploying-an-application.md

@@ -30,23 +30,18 @@ using the URL supplied by their Deis administrator.
 
 Deis supports three different ways of building applications:
 
- 1. [Heroku Buildpacks][]
- 2. [Dockerfiles][]
- 3. [Docker Images][]
-
-
 ### Buildpacks
 
 Heroku buildpacks are useful if you want to follow Heroku's best practices for building applications or if you are porting an application from Heroku.
 
-Learn how to deploy applications on Deis [using Buildpacks](using-buildpacks.md).
+Learn how to deploy applications [using Buildpacks](using-buildpacks.md).
 
 
 ### Dockerfiles
 
 Dockerfiles are a powerful way to define a portable execution environment built on a base OS of your choosing.
 
-Learn how to deploy applications on Deis [using Dockerfiles](using-dockerfiles.md).
+Learn how to deploy applications [using Dockerfiles](using-dockerfiles.md).
 
 
 ### Docker Image
@@ -55,11 +50,8 @@ Deploying a Docker image onto Deis allows you to take a Docker image from either
 or a private registry and copy it over bit-for-bit, ensuring that you are running the same
 image in development or in your CI pipeline as you are in production.
 
-Learn how to deploy applications on Deis [using Docker images](using-docker-images.md).
+Learn how to deploy applications [using Docker images](using-docker-images.md).
 
 [application]: ../reference-guide/terms.md#application
 [controller]: ../understanding-deis/components.md#controller
 [twelve-factor methodology]: http://12factor.net/
-[Heroku Buildpacks]: https://devcenter.heroku.com/articles/buildpacks
-[Dockerfiles]: https://docs.docker.com/reference/builder/
-[Docker Images]: https://docs.docker.com/engine/userguide/containers/dockerimages/