[GitHub] lucperkins closed pull request #514: General docs cleanup (WIP)

[GitBox <gi...@apache.org>]

lucperkins closed pull request #514: General docs cleanup (WIP)
URL: https://github.com/apache/bookkeeper/pull/514
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/site/docs/4.5.0/example.md b/site/docs/4.5.0/example.md
deleted file mode 100644
index 7dbc6979d..000000000
--- a/site/docs/4.5.0/example.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: Example doc
-subtitle: Just for experimentation purposes.
----
-
-{% pop ledger %}
diff --git a/site/docs/latest/example.md b/site/docs/latest/example.md
deleted file mode 100644
index 7dbc6979d..000000000
--- a/site/docs/latest/example.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: Example doc
-subtitle: Just for experimentation purposes.
----
-
-{% pop ledger %}
diff --git a/site/docs/latest/overview/overview.md b/site/docs/latest/overview/overview.md
index 8e89adb58..fe8dcf457 100644
--- a/site/docs/latest/overview/overview.md
+++ b/site/docs/latest/overview/overview.md
@@ -20,17 +20,16 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-This documentation is for Apache BookKeeper™ version `{{ site.latest_version }}`.
+This documentation is for Apache BookKeeper version **{{ site.latest_version }}**.
 
-Apache BookKeeper™ is a scalable, fault tolerant and low latency storage service optimized for realtime workloads.
-It offers `durability`, `replication` and `strong consistency` as essentials for building reliable real-time applications.
+Apache BookKeeper is a scalable, fault-tolerant, and low-latency log storage service optimized for real-time workloads. It offers durability, replication, and strong consistency as essentials for building reliable real-time applications.
 
-It is suitable for being used in following scenerios:
+BookKeeper is ideally suited for scenarios like:
 
-- [WAL](https://en.wikipedia.org/wiki/Write-ahead_logging) (Write-Ahead-Logging), e.g. HDFS [namenode](https://hadoop.apache.org/docs/r2.5.2/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithNFS.html#BookKeeper_as_a_Shared_storage_EXPERIMENTAL).
-- Message Store, e.g. [Apache Pulsar](https://pulsar.incubator.apache.org/).
-- Offset/Cursor Store, e.g. Apache Pulsar.
-- Object/Blob Store, e.g. storing snapshots to replicated state machines.
+- [Write-ahead logging](https://en.wikipedia.org/wiki/Write-ahead_logging) (WAL), for example the HDFS [NameNode](https://hadoop.apache.org/docs/r2.5.2/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithNFS.html#BookKeeper_as_a_Shared_storage_EXPERIMENTAL)
+- Durable storage for messaging systems, for example [Apache Pulsar](https://pulsar.incubator.apache.org/) (incubating)
+- Offset/cursor store, for example Apache Pulsar
+- Object/blob Store, for example storing snapshots to replicated state machines
 
 Learn more about Apache BookKeeper™ and what it can do for your organization:
 
@@ -39,19 +38,22 @@ Learn more about Apache BookKeeper™ and what it can do for your organizati
 
 Or start using Apache BookKeeper today.
 
-### Users 
+## Guide to the documentation
 
-- **Concepts**: Start with [concepts](../../getting-started/concepts). This will help you to fully understand
-    the other parts of the documentation, including the setup, integration and operation guides.
-- **Getting Started**: Install [Apache BookKeeper](../../getting-started/installation) and run bookies [locally](../../getting-started/run-locally)
-- **API**: Read the [API](../../api/overview) documentation to learn how to use Apache BookKeeper to build your applications.
-- **Deployment**: The [Deployment Guide](../../deployment/manual) shows how to deploy Apache BookKeeper to production clusters.
+You can find a full index of the BookKeeper documentation in the sidebar on the left. But if you're not sure where to start:
 
-### Administrators
+### BookKeeper users
 
-- **Operations**: The [Admin Guide](../../admin/bookies) shows how to run Apache BookKeeper on production, what are the production
-    considerations and best practices.
+- **Concepts** --- Start with the [concepts and architecture](../../getting-started/concepts) documentation. This will help you to fully understand
+    other parts of the documentation, including the setup, integration, and operations guides.
+- **Getting started** --- Install [Apache BookKeeper](../../getting-started/installation) and run bookies [locally](../../getting-started/run-locally).
+- **API** --- Read the [API](../../api/overview) documentation to learn how to use Apache BookKeeper to build your applications.
+- **Deployment** --- The [Deployment Guide](../../deployment/manual) shows you how to deploy Apache BookKeeper to production clusters.
 
-### Contributors
+### BookKeeper administrators
 
-- **Details**: Learn [design details](../../development/protocol) to know more internals.
+- **Operations** --- The [Admin Guide](../../admin/bookies) shows you how to run Apache BookKeeper in production and discusses best practices.
+
+### BookKeeper contributors
+
+- **Details** --- Learn [design details](../../development/protocol) to better understand the internals of BookKeeper.
diff --git a/site/docs/latest/security/zookeeper.md b/site/docs/latest/security/zookeeper.md
index e16be69a1..1328d0b34 100644
--- a/site/docs/latest/security/zookeeper.md
+++ b/site/docs/latest/security/zookeeper.md
@@ -5,12 +5,12 @@ prev: ../sasl
 
 ## New Clusters
 
-To enable `ZooKeeper` authentication on Bookies or Clients, there are two necessary steps:
+To enable ZooKeeper authentication on bookies or BookKeeper clients, there are two necessary steps:
 
-1. Create a `JAAS` login file and set the appropriate system property to point to it as described in [GSSAPI (Kerberos)](../sasl#notes).
-2. Set the configuration property `zkEnableSecurity` in each bookie to `true`.
+1. Create a [Java Authentication and Authorization Service](https://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service) (JAAS) login file and set the appropriate system property to point to it as described in [GSSAPI (Kerberos)](../sasl#notes).
+2. Set the configuration property [`zkEnableSecurity`](../../reference/config#zkEnableSecurity) in each bookie to `true`.
 
-The metadata stored in `ZooKeeper` is such that only certain clients will be able to modify and read the corresponding znodes.
+The metadata stored in ZooKeeper is such that only certain clients will be able to modify and read the corresponding znodes.
 The rationale behind this decision is that the data stored in ZooKeeper is not sensitive, but inappropriate manipulation of znodes can cause cluster
 disruption.
 


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services