Adding section headers to the docs (#742)

* Adding a section page for installing

* adjusting section ordering

so that the section list reads more like a story front to back

* Adjusting intro title

* removing redundant title

* Adding a body to the design section header

* Adding more to the contributing front page

* Splitting up sections in the install front page

* adding intro summary

* Better description of federation

* adding new maintainer language

* relative link

* more grammar and formatting fixes

docs/content/contributing/_index.md

@@ -1,13 +1,28 @@
 ---
-title: "Contributing"
+title: "Contributing to Athens"
 date: 2018-09-01T19:30:42-07:00
-chapter: true
-weight: 4
+weight: 3
 
 ---
 
-# Contributing
+Welcome, Gopher! We're really glad you're considering contributing to Athens. We'd like to briefly introduce you to our community before you get started.
 
-We're so glad to see you here, we hope the following pages help you understand
-the part different roles play in our community and how some decisions are made.
+We have some hard-and-fast rules in our community, like our [Code of Conduct](https://github.com/gomods/athens/blob/master/CODE_OF_CONDUCT.md), but instead of making rules pre-emptively, we try to keep in mind a shared philosophy to help us all make decisions and make new rules when we need to.
 
+## Our Philosophy Document
+
+[PHILOSOPHY.md](https://github.com/gomods/athens/blob/master/PHILOSOPHY.md) in our repository details our philosopy, and if you get involved with our project we encourage you to read it. If you're just browsing for now, here's a brief summary:
+
+- **Be Nice to Each Other** - people > code all the time, every time. We think that if we focus on our relationships with each other, we'll end up with better technology, better code, and a better community.
+- **Make Development & Testing Easy** - Well, as easy as possible. This helps us reduce cognitive load so we can focus on Athens, not setting up our dev/test environment.
+- **Focus on the Commmunity** - "If you want to go fast, go alone. If you want to go far, go together." We all try to follow this proverb. We try to get as many people involved as we can, we do (almost) everything 100% transparently, and we trust each other to do the right thing.
+
+## Where to Go from Here
+
+We hope you like what you see, and we'd love for you to get involved.
+
+If you're familiar with Git and GitHub basics, read [how to participate in the Athens community](./community-roles) to learn about how we organize ourselves and how to get started.
+
+If you're new to Git and GitHub, check out our [guide for new contributors to open source](./new), and then go on to that how to participate document I mentioned above.
+
+Finally, if you are a new maintainer of the project, we have some documentation written for you at [./maintainers](./maintainers).

docs/content/design/_index.md

@@ -1,6 +1,18 @@
 ---
-title: "Design"
+title: "The Design of Athens"
 date: 2018-09-20T15:37:49-07:00
-weight: 2
+weight: 4
 ---
 
+This section of the documentation details the design of Athens. You can read the code and ask plenty of questions (which we're always happy to answer!), but we want to take some time here to give you a head start by describing how Athens is designed in words and diagrams, rather than code.
+
+## What You'll Find Here
+
+We've split this section into two major sections:
+
+1. [Proxy internals](./proxy) - basics of the proxy architecture and major features
+2. [Communication flow](./communication) - how the proxy interacts with the outside world to fetch and store code, respond to user requests, and so on
+
+## How to Read this Section
+
+We've designed the documentation in this section as a reference, which contrasts some of the other sections. That means that you don't need to read everything here from front to back to get value from it. We anticipate that you'll get the most out of this section while you're [contributing](/contributing) to the project.

docs/content/install/_index.md

@@ -1,6 +1,23 @@
 ---
-title: "Install"
+title: "Installing Athens"
 date: 2018-09-20T15:38:01-07:00
-weight: 3
+weight: 2
 ---
 
+The Go ecosystem has always been federated and completely open. Anyone with a GitHub or GitLab (or any other supported VCS) account can effortlessly provide a library with just a `git push` (or similar). No extra accounts to create or credentials to set up.
+
+## A Federated Ecosystem
+
+We feel that Athens should keep the community federated and open, and nobody should have to change their workflow when they're building apps and libraries. So, to make sure the community can stay federated and open, we've made it easy to install Athens for everyone so that:
+
+- Anyone can run their own full-featured mirror, public or private
+- Any organization can run their own private mirror, so they can manage their private code just as they would their public code
+
+## Where to Go from Here
+
+To make sure it's easy to install, we try to provide as many ways as possible to install and run Athens:
+
+- It's written in Go, so we provide a self-contained binary. You can configure and run the binary on your machine(s) 
+    - Instructions on how to run directly from the binary are coming soon
+- We provide a [Docker image](https://hub.docker.com/r/gomods/proxy/) and [instructions on how to run it](./shared-team-instance)
+- We provide [Kubernetes](https://kubernetes.io) [Helm Charts](https://helm.sh) with [instructions on how to run Athens on Kubernetes](./install-on-kubernetes)

docs/content/intro/_index.md

@@ -1,6 +1,17 @@
 ---
-title: "Intro"
+title: "Introduction to Athens"
 date: 2018-09-20T15:38:11-07:00
 weight: 1
 ---
 
+Welcome to Athens, Gophers! We gave a very brief overview of Athens on [the home page](/), so if you want to know more, you've come to the right place!
+
+This section gives you all the details you need to understand what Athens does, why it exists, and how it fits into your workflow.
+
+# Where to Go From Here
+
+We recommend you read this section from front to back:
+
+- [Athens 101](./first-content) - the basic mechanics of Athens
+- [Download Protocol](./protocol) - the fundamental way that Athens serves Go packages
+- [Components](./components) - the different moving pieces of Athens

docs/themes/hugo-theme-learn/layouts/install/list.html

@@ -0,0 +1,8 @@
+{{ partial "header.html" . }}
+<span id="sidebar-toggle-span">
+<a href="#" id="sidebar-toggle" data-sidebar-toggle=""><i class="fa fa-bars"></i> navigation</a>
+</span>
+
+{{ .Content }}
+
+{{ partial "footer.html" . }}