Documentation: fixup the admin_guide

- Provide more concrete examples and explanation
- Cleanup the formatting to one sentence per line, this makes reviewing
  easier
- Point to existing docs on wal and snap instead of trying to duplicate
  it here again.

Documentation/0.5/admin_guide.md

@@ -1,20 +1,33 @@
-##Administration
-###Data Directory
+## Administration
 
-When first started, etcd stores its configuration into the data directory. This configuration includes the local member ID, cluster ID, and initial cluster configuration. The directory contains all data that etcd needs to operate and recover after a restart (for example in order to rejoin a cluster).
+### Data Directory
 
-If a member’s data directory is ever lost or corrupted, the user should remove the etcd member from the cluster via the [members API][0]. (The member can then be re-added to the cluster with an empty data directory, again using the [members API][0], and it will recover state).
+#### Lifecycle
 
-An etcd member restarted with previously used command line arguments but a new data directory is considered a different member. And it can potentially corrupt the cluster. If you are spinning up multiple clusters for testing it is recommended that you specify a unique initial-cluster-token for the different clusters. This can protect you from cluster corruption in case of the misconfiguration metioned above.
+When first started, etcd stores its configuration into a data directory specified by the data-dir configuration parameter.
+Configuration is stored in the write ahead log and includes: the local member ID, cluster ID, and initial cluster configuration.
+The write ahead log and snapshot files are used during member operation and to recover after a restart.
+
+If a member’s data directory is ever lost or corrupted then the user should remove the etcd member from the cluster via the [members API][members-api].
+
+A user should avoid restarting an etcd member with a data directory from an out-of-date backup.
+Using an out-of-date data directory can lead to inconsistency as the member had agreed to store information via raft then re-joins saying it needs that information again.
+For maximum safety, if an etcd member suffers any sort of data corruption or loss, it must be removed from the cluster.
+Once removed the member can be re-added with an empty data directory.
+
+[members-api]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md#members-api
+
+#### Contents
 
 The data directory has two sub-directories in it:
 
-1. wal: etcd stores its append-only log files in the wal directory. Before any command gets committed, etcd ensures that the log entry that represents the command is written to wal. The name of the wal file is <seq>-<logindex>.wal. Seq is the sequence number of log file, it starts from 0. Log index is the expected index of the first log entry written to the log file. etcd will create new wal file periodically with a higher sequence number.(TODO: how to clean old wal file)
+1. wal: write ahead log files are stored here. For details see the [wal package documentation][wal-pkg]
+2. snap: log snapshots are stored here. For details see the [snap package documentation][snap-pkg]
 
-2. snap  (TODO: format not stable)
+[wal-pkg]: http://godoc.org/github.com/coreos/etcd/wal
+[snap-pkg]: http://godoc.org/github.com/coreos/etcd/snap
 
-###Things to avoid:
-1. restart a etcd member without previous data directory
-2. restart a etcd member with different data directory
+### Cluster Lifecycle
 
-[0]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md#members-api
+If you are spinning up multiple clusters for testing it is recommended that you specify a unique initial-cluster-token for the different clusters.
+This can protect you from cluster corruption in case of mis-configuration because two members started with different cluster tokens will refuse members from each other.