Reorganized, renamed, and moved the Technical Overview information (p…

…reviously "Learning") per:

etcd-io#771 (comment)

Did some minor rewriting. Moved the Glossary out of "Learning" into the main table of contents after "FAQ".

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

content/en/docs/v3.6/dev-guide/api_concurrency_reference_v3.md

@@ -1,5 +1,6 @@
 ---
 title: "API reference: concurrency"
+weight: 3950
 ---
 
 This API reference is autogenerated from the named `.proto` files.

content/en/docs/v3.6/dev-guide/api_reference_v3.md

@@ -1,5 +1,6 @@
 ---
 title: API reference
+weight: 3900
 ---
 
 This API reference is autogenerated from the named `.proto` files.

content/en/docs/v3.6/dev-guide/features.md

@@ -6,7 +6,7 @@ description: using etcd features
 
 This document provides an overview of etcd features to help users better understand the features and related deprecation process. If you are interested in knowing about how features are developed in the etcd, please see these [development guidelines](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/features.md).
 
-The etcd features fall into three stages, experimental, stable, and unsafe. You can get the list of features by running `etcd --help`.
+The etcd features fall into three stages: experimental, stable, and unsafe. You can get the list of features by running `etcd --help`.
 
 ## Experimental
 

content/en/docs/v3.6/learning/persistent-storage-files.md → content/en/docs/v3.6/dev-guide/persistent-storage-files.md

@@ -1,18 +1,18 @@
 ---
 title: etcd persistent storage files
-weight: 2650
+weight: 4000
 description: Reference of the persistent storage format and files
 ---
 
-This document explains the etcd persistent storage format: naming, content and tools that allow developers to inspect them. Going forward the document should be extended with changes to the storage model. This document is targeted at etcd developers to help with their data recovery needs.
+This document is targeted at etcd developers to help with their data recovery needs. The document explains the etcd persistent storage format: naming, content and tools that allow developers to inspect them. The document should be kept up-to-date with changes to the storage model. 
 
 
 ## Prerequisites
 
-The following articles provide helpful background information for this document:
+The following articles provide background information relevant to this document:
 
-* etcd data model overview: https://etcd.io/docs/v3.6/learning/data_model
-* Raft overview: https://raft.github.io/raft.pdf (especially "5.3 Log replication" section).
+* The etcd data model overview: https://etcd.io/docs/v3.6/tech-overview/data_model
+* Raft overview: https://raft.github.io/raft.pdf (especially the "5.3 Log replication" section).
 
 
 ## Overview

content/en/docs/v3.6/faq.md

@@ -155,7 +155,7 @@ If none of the above suggestions clear the warnings, please [open an issue][new_
 etcd sends a snapshot of its complete key-value store to refresh slow followers and for [backups][backup]. Slow snapshot transfer times increase MTTR; if the cluster is ingesting data with high throughput, slow followers may livelock by needing a new snapshot before finishing receiving a snapshot. To catch slow snapshot performance, etcd warns when sending a snapshot takes more than thirty seconds and exceeds the expected transfer time for a 1Gbps connection.
 
 
-[api-mvcc]: ../learning/api/#revisions
+[api-mvcc]: ../tech-overview/api/#revisions
 [backend_commit_metrics]: ../metrics/#disk
 [backup]: ../op-guide/recovery/#snapshotting-the-keyspace
 [benchmark]: https://github.com/etcd-io/etcd/tree/main/tools/benchmark

content/en/docs/v3.6/learning/glossary.md → content/en/docs/v3.6/glossary.md

@@ -1,11 +1,9 @@
 ---
 title: Glossary
-weight: 2900
-description: Terms used in etcd documentation, command line, and source code
+weight: 1250
+description: Terms used in the etcd documentation, command line, and source code.
 ---
 
-This document defines the various terms used in etcd documentation, command line and source code.
-
 ## Alarm
 
 The etcd server raises an alarm whenever the cluster needs operator intervention to remain reliable.

content/en/docs/v3.6/op-guide/runtime-configuration.md

@@ -240,7 +240,7 @@ It is enabled by default.
 [cluster-reconf]: #cluster-reconfiguration-operations
 [conf-adv-peer]: ../configuration#clustering
 [conf-name]: ../configuration#member
-[design-learner]: ../../learning/design-learner
+[design-learner]: ../../tech-overview/design-learner
 [disaster recovery]: ../recovery
 [error cases when promoting a member]: #error-cases-when-promoting-a-learner-member
 [fault tolerance table]: /docs/v2.3/admin_guide/#fault-tolerance-table

content/en/docs/v3.6/quickstart.md

@@ -45,14 +45,16 @@ cluster of etcd:
 
 Learn about more ways to configure and use etcd from the following pages:
 
-- Explore the gRPC [API][].
+- Read a [technical overview][tech-overview] describing the design and architecture of etcd
 - Set up a [multi-machine cluster][clustering].
+- Explore the gRPC [API][].
 - Learn how to [configure][] etcd.
 - Find [language bindings and tools][integrations].
 - Use TLS to [secure an etcd cluster][security].
 - [Tune etcd][tuning].
 
-[api]: /docs/{{< param version >}}/learning/api
+[tech-overview]: /docs/{{< param version >}}/tech-overview
+[api]: /docs/{{< param version >}}/tech-overview/api
 [clustering]: /docs/{{< param version >}}/op-guide/clustering
 [configure]: /docs/{{< param version >}}/op-guide/configuration
 [integrations]: /docs/{{< param version >}}/integrations

content/en/docs/v3.6/tech-overview/_index.md

@@ -0,0 +1,5 @@
+---
+title: Technical Overview
+weight: 950
+description: Conceptual information about the etcd data model, architecture, and design
+---

content/en/docs/v3.6/learning/api.md → content/en/docs/v3.6/tech-overview/api.md

@@ -4,11 +4,11 @@ weight: 2625
 description: etcd API central design overview
 ---
 
-This document is meant to give an overview of the v3 etcd APIs central design.
-This should not be mistaken with etcd v2 API, deprecated in etcd v3.5.
-It is by no means all encompassing, but intended to focus on the basic ideas needed to understand etcd without the distraction of less common API calls.
+This document is meant to give an overview of the v3 etcd API's central design.
+Do not confuse the v3 API with the etcd v2 API, which was deprecated in etcd v3.5.
+This overvieww is not comprehensive. It focuses on the basic ideas needed to understand etcd without the distraction of less common API calls.
 All etcd APIs are defined in [gRPC services][grpc-service], which categorize remote procedure calls (RPCs) understood by the etcd server.
-A full listing of all etcd RPCs are documented in markdown in the [gRPC API listing][grpc-api].
+A full listing of etcd RPCs are documented in Markdown in the [gRPC API listing][grpc-api].
 
 ## gRPC Services
 

content/en/docs/v3.6/learning/api_guarantees.md → content/en/docs/v3.6/tech-overview/api_guarantees.md

@@ -1,13 +1,12 @@
 ---
-title: etcd API guarantees
-weight: 2750
-description: API guarantees made by etcd
+title: Key-value API guarantees
+weight: 2650
+description: API key-value guarantees made by etcd
 ---
 
-etcd is a consistent and durable key value store.
-The key value store is exposed through [gRPC Services].
-etcd ensures the strongest consistency and durability guarantees for a distributed system.
-This specification enumerates the API guarantees made by etcd.
+etcd is a consistent and durable key-value (KV) store. The key value store is exposed through [gRPC Services].
+
+etcd ensures the strongest consistency and durability guarantees for a distributed system. This specification enumerates the API guarantees made by etcd.
 
 ### APIs to consider
 
@@ -23,55 +22,55 @@ This specification enumerates the API guarantees made by etcd.
   * [Revoke]
   * [Keep alive](../api/#keep-alives)
 
-KV API allows for direct reading and manipulation of key value store.
-Watch API allows subscribing to key value store changes.
-Lease API allows assigning a time to live to a key.
+The KV API allows for direct reading and manipulation of key value store.
+
+The Watch API allows subscribing to key value store changes.
+
+The Lease API allows assigning a time to live to a key.
 
-Both KV and Watch APIs allow access to not only the latest versions of keys, but
-also previous versions are accessible within a continuous history window, limited
+Both the KV and Watch APIs allow access to the latest versions of keys, plus all previous versions within a continuous history window limited
 by a compaction operation.
 
-Calling KV API will take an immediate effect, while Watch API will return with some unbounded delay.
-In correctly working etcd cluster you should expect to see watch events to appear with 10ms delay after them happening.
-However, there is no limit and events in unhealthy clusters might never arrive.
+Calling the KV API has immediate effect. 
+
+The Watch API returns after an unbounded but usually short delay. In a correctly working etcd cluster, expect to see watch events appear within 10ms after they occur. However, the delay has no limit and events in unhealthy clusters might never arrive.
 
 ## KV APIs
 
-etcd ensures durability and strict serializability for all KV api calls.
-Those are the strongest isolation guarantee of distributed transactional database systems.
+etcd ensures durability and strict serializability for all KV API calls, the strongest isolation guarantee available in distributed transactional database systems.
 
 ### Durability
 
-Any completed operations are durable. All accessible data is also durable data.
-A read will never return data that has not been made durable.
+Any completed operations is durable. All accessible data is also durable data. A read never returns data that has not been made durable.
 
 ### Strict serializability
 
-KV Service operations are atomic and occur in a total order, consistent with
-real-time order of those operations. Total order is implied through [revision].
+KV Service operations are atomic and occur in a total order, consistent with the real-time order of those operations. Total order is implied through [revision].
+
 Read more about [strict serializability].
 
-Strict serializability implies other weaker guarantees that might be easier to understand:
+Strict serializability implies the weaker guarantees of [atomicity] and [liearizability].
 
 #### Atomicity
 
 All API requests are atomic; an operation either completes entirely or not at
-all. For watch requests, all events generated by one operation will be in one
-watch response. Watch never observes partial events for a single operation.
+all. All events generated by one Watch operation are in one
+Watch response. Watch never observes partial events for a single operation.
 
 #### Linearizability
 
-From the perspective of client, linearizability provides useful properties which
-make reasoning easily. This is a clean description quoted from
-[the original paper][linearizability]: `Linearizability provides the illusion
-that each operation applied by concurrent processes takes effect instantaneously
-at some point between its invocation and its response.`
+From the perspective of client, linearizability provides useful properties that
+facilitate reasoning about operations. This is a description quoted from
+[the original paper][linearizability]: 
+
+> Linearizability provides the illusion that each operation applied by concurrent processes takes effect instantaneously
+at some point between its invocation and its response.
 
-For example, consider a client completing a write at time point 1 (*t1*). A
+For example, consider a client completing a write at time *t1*. A
 client issuing a read at *t2* (for *t2* > *t1*) should receive a value at least
-as recent as the previous write, completed at *t1*. However, the read might
-actually complete only by *t3*. Linearizability guarantees the read returns the
-most current value. Without linearizability guarantee, the returned value,
+as recent as the write completed at *t1*. However, the read might
+not complete until *t3* (> *t2*). Linearizability guarantees the read returns the
+most current value. Without the linearizability guarantee, the returned value,
 current at *t2* when the read began, might be "stale" by *t3* because a
 concurrent write might happen between *t2* and *t3*.
 
@@ -84,12 +83,12 @@ removes the performance penalty of linearized accesses' reliance on live consens
 
 ## Watch APIs
 
-Watches make guarantees about events:
+Watches make these guarantees about events:
 * Ordered - events are ordered by revision.
-  An event will never appear on a watch if it precedes an event in time that
+  An event never appears on a watch if it precedes an event that
   has already been posted.
-* Unique - an event will never appear on a watch twice.
-* Reliable - a sequence of events will never drop any subsequence of events
+* Unique - an event never appears on a watch twice.
+* Reliable - a sequence of events never drops any sub-sequence of events
   within the available history window. If there are events ordered in time as
   a < b < c, then if the watch receives events a and c, it is guaranteed to
   receive b as long b is in the available history window.

content/en/docs/v3.6/learning/design-client.md → content/en/docs/v3.6/tech-overview/design-client.md

@@ -4,12 +4,6 @@ weight: 2250
 description: Client architectural decisions & their implementation details
 ---
 
-etcd Client Design
-==================
-
-*Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.)*
-
-
 Introduction
 ============
 
@@ -138,3 +132,5 @@ Client-side keepalive ping still does not reason about network partitions. Strea
 ![client-balancer-figure-07.png](../img/client-balancer-figure-07.png)
 
 Currently, retry logic is handled manually as an interceptor. This may be simplified via [official gRPC retries](https://github.com/grpc/proposal/blob/master/A6-client-retries.md).
+
+*Authors: Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.)*

content/en/docs/v3.6/learning/design-learner.md → content/en/docs/v3.6/tech-overview/design-learner.md

@@ -4,11 +4,6 @@ weight: 2375
 description: Mitigating common challenges with membership reconfiguration
 ---
 
-etcd Learner
-============
-
-*Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.)*
-
 
 Background
 ==========
@@ -128,3 +123,5 @@ Reference
 - Use case: [etcd#3715](https://github.com/etcd-io/etcd/issues/3715)
 - Use case: [etcd#8888](https://github.com/etcd-io/etcd/issues/8888)
 - Use case: [etcd#10114](https://github.com/etcd-io/etcd/issues/10114)
+
+*Authors: Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.)*

content/en/docs/v3.6/learning/why.md → content/en/docs/v3.6/tech-overview/why.md

@@ -1,7 +1,7 @@
 ---
 title: etcd versus other key-value stores
 weight: 2875
-description: History and use of etcd & comparison with other tools
+description: History and use of etcd, and comparison with other tools
 ---
 
 The name "etcd" originated from two ideas, the unix "/etc" folder and "d"istributed systems. The "/etc" folder is a place to store configuration data for a single system whereas etcd stores configuration information for large scale distributed systems. Hence, a "d"istributed "/etc" is "etcd".

content/en/docs/v3.6/upgrades/upgrade_3_3.md

@@ -399,7 +399,7 @@ _, err := kvc.Get(ctx, "a")
 +  if s.Code() == codes.Canceled
 ```
 
-[The new client balancer](/docs/{{< param version >}}/learning/design-client/) uses an asynchronous resolver to pass endpoints to the gRPC dial function. As a result, [v3.3.14](https://github.com/etcd-io/etcd/releases/tag/v3.3.14) or later requires `grpc.WithBlock` dial option to wait until the underlying connection is up.
+[The new client balancer](/docs/{{< param version >}}/tech-overview/design-client/) uses an asynchronous resolver to pass endpoints to the gRPC dial function. As a result, [v3.3.14](https://github.com/etcd-io/etcd/releases/tag/v3.3.14) or later requires `grpc.WithBlock` dial option to wait until the underlying connection is up.
 
 ```diff
 import (

content/en/docs/v3.6/upgrades/upgrade_3_4.md

@@ -93,7 +93,7 @@ _, err := kvc.Get(ctx, "a")
 
 #### Require `grpc.WithBlock` for client dial
 
-[The new client balancer](/docs/{{< param version >}}/learning/design-client/) uses an asynchronous resolver to pass endpoints to the gRPC dial function. As a result, v3.4 client requires `grpc.WithBlock` dial option to wait until the underlying connection is up.
+[The new client balancer](/docs/{{< param version >}}/tech-overview/design-client/) uses an asynchronous resolver to pass endpoints to the gRPC dial function. As a result, v3.4 client requires `grpc.WithBlock` dial option to wait until the underlying connection is up.
 
 ```diff
 import (