Move diagrams out of top-level docs/ directory and merge

docs/devel/developer-guide.md into docs/devel/README.md

Author: David Oppenheimer

docs/README.md

@@ -28,7 +28,7 @@ certainly want the docs that go with that version.</h1>
 * The [Cluster Admin's guide](admin/README.md) is for anyone setting up
   a Kubernetes cluster or administering it.
 
-* The [Developer guide](devel/developer-guide.md) is for anyone wanting to write
+* The [Developer guide](devel/README.md) is for anyone wanting to write
   programs that access the kubernetes API, write plugins or extensions, or
   modify the core code of kubernetes.
 

docs/architecture.dia renamed to docs/design/architecture.dia

@@ -24,7 +24,7 @@ certainly want the docs that go with that version.</h1>
 
 A running Kubernetes cluster contains node agents (kubelet) and master components (APIs, scheduler, etc), on top of a distributed storage solution. This diagram shows our desired eventual state, though we're still working on a few things, like making kubelet itself (all our components, really) run within containers, and making the scheduler 100% pluggable.
 
-![Architecture Diagram](../architecture.png?raw=true "Architecture overview")
+![Architecture Diagram](architecture.png?raw=true "Architecture overview")
 
 ## The Kubernetes Node
 

docs/design/architecture.md

@@ -20,27 +20,35 @@ certainly want the docs that go with that version.</h1>
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
-# Developing Kubernetes
+# Kubernetes Developer Guide
 
-Docs in this directory relate to developing Kubernetes.
+The developer guide is for anyone wanting to either write code which directly accesses the
+kubernetes API, or to contribute directly to the kubernetes project.
+It assumes some familiarity with concepts in the [User Guide](../user-guide/README.md) and the [Cluster Admin
+Guide](../admin/README.md).
 
-* **On Collaborative Development** ([collab.md](collab.md)): info on pull requests and code reviews.
 
-* **Development Guide** ([development.md](development.md)): Setting up your environment tests.
+## The process of developing and contributing code to the Kubernetes project
 
-* **Making release notes** ([making-release-notes.md](making-release-notes.md)): Generating release nodes for a new release.
-
-* **Hunting flaky tests** ([flaky-tests.md](flaky-tests.md)): We have a goal of 99.9% flake free tests.
-  Here's how to run your tests many times.
+* **On Collaborative Development** ([collab.md](collab.md)): Info on pull requests and code reviews.
 
 * **GitHub Issues** ([issues.md](issues.md)): How incoming issues are reviewed and prioritized.
 
-* **Logging Conventions** ([logging.md](logging.md)]: Glog levels.
-
 * **Pull Request Process** ([pull-requests.md](pull-requests.md)): When and why pull requests are closed.
 
-* **Releasing Kubernetes** ([releasing.md](releasing.md)): How to create a Kubernetes release (as in version)
-  and how the version information gets embedded into the built binaries.
+* **Faster PR reviews** ([faster_reviews.md](faster_reviews.md)): How to get faster PR reviews.
+
+* **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds that pass CI.
+
+
+## Setting up your dev environment, coding, and debugging
+
+* **Development Guide** ([development.md](development.md)): Setting up your development environment.
+
+* **Hunting flaky tests** ([flaky-tests.md](flaky-tests.md)): We have a goal of 99.9% flake free tests.
+  Here's how to run your tests many times.
+
+* **Logging Conventions** ([logging.md](logging.md)]: Glog levels.
 
 * **Profiling Kubernetes** ([profiling.md](profiling.md)): How to plug in go pprof profiler to Kubernetes.
 
@@ -51,9 +59,39 @@ Docs in this directory relate to developing Kubernetes.
 * **Coding Conventions** ([coding-conventions.md](coding-conventions.md)):
   Coding style advice for contributors.
 
-* **Faster PR reviews** ([faster_reviews.md](faster_reviews.md)): How to get faster PR reviews.
 
-* **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds to pass CI.
+## Developing against the Kubernetes API
+
+* API objects are explained at [http://kubernetes.io/third_party/swagger-ui/](http://kubernetes.io/third_party/swagger-ui/).
+
+* **Annotations** ([docs/user-guide/annotations.md](../user-guide/annotations.md)): are for attaching arbitrary non-identifying metadata to objects.
+  Programs that automate Kubernetes objects may use annotations to store small amounts of their state.
+
+* **API Conventions** ([api-conventions.md](api-conventions.md)):
+  Defining the verbs and resources used in the Kubernetes API.
+
+* **API Client Libraries** ([client-libraries.md](client-libraries.md)):
+  A list of existing client libraries, both supported and user-contributed.
+
+
+## Writing plugins
+
+* **Authentication Plugins** ([docs/admin/authentication.md](../admin/authentication.md)):
+  The current and planned states of authentication tokens.
+
+* **Authorization Plugins** ([docs/admin/authorization.md](../admin/authorization.md)):
+  Authorization applies to all HTTP requests on the main apiserver port.
+  This doc explains the available authorization implementations.
+
+* **Admission Control Plugins** ([admission_control](../design/admission_control.md))
+
+
+## Building releases
+
+* **Making release notes** ([making-release-notes.md](making-release-notes.md)): Generating release nodes for a new release.
+
+* **Releasing Kubernetes** ([releasing.md](releasing.md)): How to create a Kubernetes release (as in version)
+  and how the version information gets embedded into the built binaries.
 
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->

docs/architecture.png renamed to docs/design/architecture.png

@@ -32,7 +32,7 @@ certainly want the docs that go with that version.</h1>
 
 <!-- END MUNGE: GENERATED_TOC -->
 
-The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster.  Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/devel/developer-guide.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project.
+The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster.  Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/devel/README.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project.
 
 Please ensure you have completed the [prerequisites for running examples from the user guide](prereqs.md).