Documentation: add 'why.md'

Documentation/docs.md

@@ -42,7 +42,7 @@ Administrators who need to create reliable and scalable key-value stores for the
 
 To learn more about the concepts and internals behind etcd, read the following pages:
 
- - Why etcd (TODO)
+ - [Why etcd][why] (TODO)
  - [Understand data model][data_model]
  - [Understand APIs][understand_apis]
  - [Glossary][glossary]
@@ -63,6 +63,7 @@ Answers to [common questions] about etcd.
 [conf]: op-guide/configuration.md
 [system-limit]: dev-guide/limit.md
 [common questions]: faq.md
+[why]: learning/why.md
 [data_model]: learning/data_model.md
 [demo]: demo.md
 [download_build]: dl_build.md

Documentation/learning/why.md

@@ -0,0 +1,19 @@
+# Why etcd
+
+etcd stores metadata in a consistent and fault-tolerant way. Distributed systems use etcd as a consistent key-value store for configuration management, service discovery, and coordinating distributed work. Common distributed patterns using etcd include leader election, [distributed locks][etcd-concurrency], and monitoring machine liveness.
+
+## Use cases
+
+- Container Linux by CoreOS: Application running on [Container Linux][container-linux] gets automatic, zero-downtime Linux kernel updates. Container Linux uses [locksmith] to coordinate updates. locksmith implements a distributed semaphore over etcd to ensure only a subset of a cluster is rebooting at any given time.
+- [Kubernetes][kubernetes] stores configuration data into etcd for service discovery and cluster management; etcd's consistency is crucial for correctly scheduling and operating services. The Kubernetes API server persists cluster state into etcd. It uses etcd's watch API to monitor the cluster and roll out critical configuration changes.
+
+
+## Features and system comparisons
+
+TODO
+
+[etcd-concurrency]: https://godoc.org/github.com/coreos/etcd/clientv3/concurrency
+[container-linux]: https://coreos.com/why
+[locksmith]: https://github.com/coreos/locksmith
+[kubernetes]: http://kubernetes.io/docs/whatisk8s
+