Merge pull request #225 from slack/refactor-docs

proposal: refactor quickstart and docs

Author: slack

Makefile

@@ -32,7 +32,7 @@ deps:
 	pip install -r requirements.txt
 
 test: build
-	grep -q '<title>Deis Documentation</title>' _build/html/index.html
+	grep -q '<title>Deis Workflow Documentation</title>' _build/html/index.html
 	@echo
 	@echo "Test finished. The HTML pages are in $(BUILDDIR)."
 

README.md

@@ -6,7 +6,7 @@
 
 Deis Workflow is the second major release (v2) of the Deis PaaS. If you are looking for the CoreOS-based PaaS visit [https://github.com/deis/deis](https://github.com/deis/deis).
 
-If you are looking to **get started** with **Deis Workflow** read the [Quick Start Guide](src/installing-workflow/quickstart.md) in this repository or on [Read the Docs](https://docs-v2.readthedocs.org/en/latest/).
+If you are looking to **get started** with **Deis Workflow** read the [Quick Start Guide](src/quickstart/index.md) in this repository or on [Read the Docs](https://docs-v2.readthedocs.org/en/latest/).
 
 Visit [https://deis.com](https://deis.com) for more information on [why you should use Deis Workflow](https://deis.com/why-deis/) or [learn about its features](https://deis.com/how-it-works/).
 

mkdocs.yml

@@ -2,51 +2,65 @@
 # NOTE: titles need to be capitalized here to work around MkDocs automatically downcasing title
 # names
 #
-site_name: Deis Documentation
+site_name: Deis Workflow Documentation
 pages:
-  - Welcome: index.md
-  - Quick Start: installing-workflow/quickstart.md
+  - Home: index.md
+  - Quick Start:
+    - Overview: quickstart/index.md
+    - Install CLI Tools: quickstart/install-cli-tools.md
+    - AWS:
+      - Boot: quickstart/provider/aws/boot.md
+      - DNS: quickstart/provider/aws/dns.md
+      - Install Workflow: quickstart/provider/aws/install-aws.md
+    - GKE:
+      - Boot: quickstart/provider/gke/boot.md
+      - DNS: quickstart/provider/gke/dns.md
+      - Install Workflow: quickstart/provider/gke/install-gke.md
+    - Vagrant:
+      - Boot: quickstart/provider/vagrant/boot.md
+      - DNS: quickstart/provider/vagrant/dns.md
+      - Install Workflow: quickstart/provider/vagrant/install-vagrant.md
+    - Deploy Your First App: quickstart/deploy-an-app.md
   - Understanding Workflow:
     - Concepts: understanding-workflow/concepts.md
     - Architecture: understanding-workflow/architecture.md
     - Components: understanding-workflow/components.md
   - Installing Workflow:
-    - Quick Start: installing-workflow/quickstart.md
+    - Installing Workflow: installing-workflow/index.md
     - System Requirements: installing-workflow/system-requirements.md
-    - Installing Workflow: installing-workflow/installing-deis-workflow.md
     - Configuring Object Storage: installing-workflow/configuring-object-storage.md
-  - Using Workflow:
-    - Installing the Client: using-workflow/installing-the-client.md
-    - Registering a User: using-workflow/registering-a-user.md
-    - Deploying an Application: using-workflow/deploying-an-application.md
-    - Process Types and the Procfile: using-workflow/process-types-and-the-procfile.md
-    - Using Buildpacks: using-workflow/using-buildpacks.md
-    - Using Dockerfiles: using-workflow/using-dockerfiles.md
-    - Using Docker Images: using-workflow/using-docker-images.md
-    - Configuring an Application: using-workflow/configuring-an-application.md
-    - Managing an Application: using-workflow/managing-an-application.md
-    - Application SSL Certificates: using-workflow/application-ssl-certificates.md
+  - Users:
+    - Command Line Interface: users/cli.md
+    - Users and Registration: users/registration.md
+    - SSH Keys: users/ssh-keys.md
+  - Applications:
+    - Deploying Apps: applications/deploying-apps.md
+    - Buildpacks: applications/using-buildpacks.md
+    - Dockerfiles: applications/using-dockerfiles.md
+    - Docker Images: applications/using-docker-images.md
+    - Managing App Processes: applications/managing-app-processes.md
+    - Managing App Configuration: applications/managing-app-configuration.md
+    - Managing App Lifecycle: applications/managing-app-lifecycle.md
+    - Resource Limits: applications/managing-resource-limits.md
+    - Domains and Routing: applications/domains-and-routing.md
+    - SSL Certificates: applications/ssl-certificates.md
   - Managing Workflow:
+    - Configuring Components: managing-workflow/component-configuration.md
     - Configuring Load Balancers: managing-workflow/configuring-load-balancers.md
     - Configuring DNS: managing-workflow/configuring-dns.md
-    - Operational Tasks: managing-workflow/operational-tasks.md
     - Platform Logging: managing-workflow/platform-logging.md
     - Platform Monitoring: managing-workflow/platform-monitoring.md
     - Production Deployments: managing-workflow/production-deployments.md
     - Security Considerations: managing-workflow/security-considerations.md
     - Platform SSL: managing-workflow/platform-ssl.md
     - Upgrading Workflow: managing-workflow/upgrading-workflow.md
-  - Customizing Workflow:
-    - CLI Plugins: customizing-workflow/cli-plugins.md
-    - Tuning Component Settings: customizing-workflow/tuning-component-settings.md
   - Troubleshooting:
     - Troubleshooting with kubectl: troubleshooting/troubleshooting.md
   - Roadmap:
     - Planning Process: roadmap/planning-process.md
     - Roadmap: roadmap/roadmap.md
     - Release Schedule: roadmap/release-schedule.md
     - Release Checklist: roadmap/release-checklist.md
-    - Test Plan: roadmap/test-plan.md
   - Contributing:
     - Overview: contributing/overview.md
     - Design Documents: contributing/design-documents.md
@@ -62,7 +76,6 @@ pages:
     - Creating a Self-Signed SSL Certificate: reference-guide/creating-a-self-signed-ssl-certificate.md
     # FIXME (bacongobbler): our custom deis theme only supports a toctree depth of 2 due to css issues
     - Controller API v2.0: reference-guide/controller-api/v2.0.md
-  - FAQ: faq.md
 theme_dir: themes/deis
 docs_dir: src
 markdown_extensions:

…ing-workflow/deploying-an-application.md src/applications/deploying-apps.mdsrc/using-workflow/deploying-an-application.md renamed to src/applications/deploying-apps.md src/using-workflow/deploying-an-application.md renamed to src/applications/deploying-apps.md

@@ -2,46 +2,48 @@
 
 An [Application][] is deployed to Deis using `git push` or the `deis` client.
 
-
 ## Supported Applications
 
-Deis can deploy any application or service that can run inside a Docker container.  In order to be scaled horizontally, applications must follow the [Twelve-Factor App][] methodology and store any application state in external backing services.
+Deis Workflow can deploy any application or service that can run inside a Docker container.  In order to be scaled
+horizontally, applications must follow the [Twelve-Factor App][] methodology and store any application state in external
+backing services.
 
-For example, if your application persists state to the local filesystem -- common with content management systems like Wordpress and Drupal -- it cannot be scaled horizontally using `deis scale`.
+For example, if your application persists state to the local filesystem -- common with content management systems like
+Wordpress and Drupal -- it cannot be scaled horizontally using `deis scale`.
 
 Fortunately, most modern applications feature a stateless application tier that can scale horizontally inside Deis.
 
-
 ## Login to the Controller
 
 !!! important
-	if you haven't yet, now is a good time to [install the client](installing-the-client.md) and [register](registering-a-user.md).
+	if you haven't yet, now is a good time to [install the client][install client] and [register](../users/registration.md).
 
 Before deploying an application, users must first authenticate against the Deis [Controller][]
 using the URL supplied by their Deis administrator.
 
-    $ deis login http://deis.example.com
-    username: deis
-    password:
-    Logged in as deis
-
+```
+$ deis login http://deis.example.com
+username: deis
+password:
+Logged in as deis
+```
 
 ## Select a Build Process
 
-Deis supports three different ways of building applications:
+Deis Workflow supports three different ways of building applications:
 
 ### 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 [using Buildpacks](using-buildpacks.md).
+Learn how to deploy applications [using Buildpacks](../applications/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 [using Dockerfiles](using-dockerfiles.md).
+Learn how to deploy applications [using Dockerfiles](../applications/using-dockerfiles.md).
 
 
 ### Docker Image
@@ -50,8 +52,9 @@ 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 [using Docker images](using-docker-images.md).
+Learn how to deploy applications [using Docker images](../applications/using-docker-images.md).
 
+[install client]: ../users/cli.md#installation
 [application]: ../reference-guide/terms.md#application
 [controller]: ../understanding-workflow/components.md#controller
 [Twelve-Factor App]: http://12factor.net/

src/applications/domains-and-routing.md

@@ -0,0 +1,22 @@
+## Domains and Routing
+
+You can use `deis domains` to add or remove custom domains to your application:
+
+    $ deis domains:add hello.bacongobbler.com
+    Adding hello.bacongobbler.com to finest-woodshed... done
+
+Once that's done, you can go into your DNS registrar and set up a CNAME from the new
+appname to the old one:
+
+    $ dig hello.deisapp.com
+    [...]
+    ;; ANSWER SECTION:
+    hello.bacongobbler.com.         1759    IN    CNAME    finest-woodshed.deisapp.com.
+    finest-woodshed.deisapp.com.    270     IN    A        172.17.8.100
+
+!!! note
+    Setting a CNAME for your root domain can cause issues. Setting your @ record
+    to be a CNAME causes all traffic to go to the other domain, including mail and the SOA
+    ("start-of-authority") records. It is highly recommended that you bind a subdomain to
+    an application, however you can work around this by pointing the @ record to the
+    address of the load balancer (if any).

…g-workflow/configuring-an-application.md …plications/managing-app-configuration.mdsrc/using-workflow/configuring-an-application.md renamed to src/applications/managing-app-configuration.md src/using-workflow/configuring-an-application.md renamed to src/applications/managing-app-configuration.md

@@ -2,7 +2,7 @@
 
 A Deis application [stores config in environment variables][].
 
-## Configure the Application
+## Setting Environment Variables
 
 Use `deis config` to modify environment variables for a deployed application.
 
@@ -51,29 +51,6 @@ the application to an external PostgreSQL database.
 
 Detachments can be performed with `deis config:unset`.
 
-## Custom Domains
-
-You can use `deis domains` to add or remove custom domains to your application:
-
-    $ deis domains:add hello.bacongobbler.com
-    Adding hello.bacongobbler.com to finest-woodshed... done
-
-Once that's done, you can go into your DNS registrar and set up a CNAME from the new
-appname to the old one:
-
-    $ dig hello.deisapp.com
-    [...]
-    ;; ANSWER SECTION:
-    hello.bacongobbler.com.         1759    IN    CNAME    finest-woodshed.deisapp.com.
-    finest-woodshed.deisapp.com.    270     IN    A        172.17.8.100
-
-!!! note
-    Setting a CNAME for your root domain can cause issues. Setting your @ record
-    to be a CNAME causes all traffic to go to the other domain, including mail and the SOA
-    ("start-of-authority") records. It is highly recommended that you bind a subdomain to
-    an application, however you can work around this by pointing the @ record to the
-    address of the load balancer (if any).
-
 
 ## Custom Health Checks
 
@@ -149,38 +126,6 @@ Configured health checks also modify the default application deploy behavior.
 When starting a new pod, Workflow will wait for the health check to pass before
 moving onto the next pod.
 
-## Track Changes
-
-Each time a build or config change is made to your application, a new [release][] is created.
-Track changes to your application using `deis releases`.
-
-    $ deis releases
-    === peachy-waxworks Releases
-    v4      3 minutes ago                     gabrtv deployed d3ccc05
-    v3      1 hour 17 minutes ago             gabrtv added DATABASE_URL
-    v2      6 hours 2 minutes ago             gabrtv deployed 7cb3321
-    v1      6 hours 2 minutes ago             gabrtv deployed deis/helloworld
-
-
-## Rollback the Application
-
-Use `deis rollback` to revert to a previous release.
-
-    $ deis rollback v2
-    Rolled back to v2
-
-    $ deis releases
-    === folksy-offshoot Releases
-    v5      Just now                          gabrtv rolled back to v2
-    v4      4 minutes ago                     gabrtv deployed d3ccc05
-    v3      1 hour 18 minutes ago             gabrtv added DATABASE_URL
-    v2      6 hours 2 minutes ago             gabrtv deployed 7cb3321
-    v1      6 hours 3 minutes ago             gabrtv deployed deis/helloworld
-
-!!! note
-    All releases (including rollbacks) append to the release ledger.
-
-
 [attached resources]: http://12factor.net/backing-services
 [stores config in environment variables]: http://12factor.net/config
 [release]: ../reference-guide/terms.md#release