Polish web-site documents

_data/navigation.yml

@@ -35,6 +35,8 @@ docs:
         url: /docs/batch-example/
       - title: "Filter Example"
         url: /docs/filter-by-sql92-example/
+      - title: "FAQ"
+        url: /docs/faq/
 
   - title: Deployment & Operations
     children:
@@ -51,7 +53,7 @@ docs:
         url: /docs/code-guidelines/
       #- title: "Branching Model"
       #  url: /docs/branching-model
-      - title: "Pull Request"
+      - title: "Manage Pull Request"
         url: /docs/pull-request/
       - title: "Release Manual"
         url: /docs/release-manual
@@ -76,8 +78,7 @@ docs:
         url: /release_notes/release-notes-4.0.0-incubating/
   - title: RoadMap
     url: /docs/roadmap/
-  - title: FAQ
-    url: /docs/faq/
+
 
 about:
   - title: Team

_docs/01-quick-start-guide.md

@@ -5,7 +5,8 @@ excerpt: "How to quickly install and setup Apache RocketMQ."
 modified: 2016-12-29T15:01:43-04:00
 ---
 
-This quick start guide is a detailed instruction of setting up RocketMQ messaging system on a local machine and sending/receiving messages.
+This quick start guide is a detailed instruction of setting up RocketMQ messaging system on your local machine to send 
+and receive messages.
 
 {% include toc %}
 
@@ -42,7 +43,7 @@ This quick start guide is a detailed instruction of setting up RocketMQ messagin
   > tail -f ~/logs/rocketmqlogs/broker.log 
   The broker[%s, 172.30.30.233:10911] boot success...
 ```
-  
+
 
 # Send & Receive Messages
 

_docs/02-motivation.md

@@ -4,16 +4,25 @@ permalink: /docs/motivation/
 modified: 2016-12-16T15:01:43-04:00
 ---
 
-At early stages, we constructed our distributed messaging middleware based on ActiveMQ 5.x(prior to 5.3). Our multinational business uses it for async communication, search, social network activity stream, data pipeline, even in its trade processes. As our trade business throughput rises, pressure originating from our messaging cluster also become urgent.
+At early stages, we constructed our distributed messaging middleware based on ActiveMQ 5.x(prior to 5.3). Our 
+multinational business uses it for asynchronous communication, search, social network activity stream, data pipeline,
+even in its trade processes. As our trade business throughput rises, pressure originating from our messaging cluster
+also becomes urgent.
 
 {% include toc %}
 
 # Why RocketMQ ?
 
-Based on our research, with increased queues and virtual topics in use, ActiveMQ IO module reaches a bottleneck. We tried our best to solve this problem through throttling, circuit breaker or degradation, but it didn't work well. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements especially low latency and high reliability, see [here](/rocketmq/how-to-support-more-queues-in-rocketmq/) for details.
+Based on our research, with increased queues and virtual topics in use, ActiveMQ IO module reaches a bottleneck. We 
+tried our best to solve this problem through throttling, circuit breaker or degradation, but it did not work well. So 
+we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our 
+requirements especially in terms of low latency and high reliability, see [here](/rocketmq/how-to-support-more-queues-in-rocketmq/) for details.
 
-In this context, we decided to invent a new messaging engine to handle a broader set of use cases, ranging from traditional pub/sub scenarios to high volume realtime zero-loss tolerance transaction system. We believe this solution can be beneficial, so we would like to open source it to the community. Today, more than 100 companies are using the open source version of RocketMQ in their business. We also published a commercial distribution based on RocketMQ, a Platform as a Service (PaaS) product called the
-[Alibaba Cloud Platform](https://intl.aliyun.com/).
+In this context, we decided to invent a new messaging engine to handle a broader set of use cases, ranging from 
+traditional pub/sub scenarios to high volume real-time zero-loss tolerance transaction system. We believe this solution
+can be beneficial, so we would like to open source it to the community. Today, more than 100 companies are using the 
+open source version of RocketMQ in their business. We also published a commercial distribution based on RocketMQ, a PaaS
+ product called the [Alibaba Cloud Platform](https://intl.aliyun.com/).
 
 
 The following table demonstrates the comparison between RocketMQ, ActiveMQ and Kafka (Apache's most popular messaging solutions according to [awesome-java](https://github.com/akullpp/awesome-java)):

_docs/03-core-concept.md

@@ -6,7 +6,7 @@ modified: 2016-12-16T15:01:43-04:00
 
 ![RocketMQ model](/assets/images/rmq-model.png)
 
-From the above model, we can look deeper into some topics about messaging system design:
+According to the above model, we can dig deeper into some topics about messaging system design:
 
 {% include toc %}
 
@@ -23,9 +23,9 @@ A producer sends messages generated by the business application systems to broke
 
 ## Producer Group
 
-Producers of the same role are grouped together. A different producer instance of the same producer group may be contacted by a broker to commit or roll back a transaction in case the original producer crashed after starting the transaction. 
+Producers of the same role are grouped together. A different producer instance of the same producer group may be contacted by a broker to commit or roll back a transaction in case the original producer crashed after the transaction.
 
-**Warning**: Considering the provided producer is sufficiently powerful at sending messages, only one instance is allowed per producer group and process to avoid unnecessarily initializing of producer instances.
+**Warning**: Considering the provided producer is sufficiently powerful at sending messages, only one instance is allowed per producer group to avoid unnecessary initialization of producer instances.
 
 # Consumer
 
@@ -37,39 +37,39 @@ A Consumer pulls messages from brokers and feeds them into application. In persp
 
 ## PushConsumer
 
-  Push consumer, on the other hand, encapsulates message pulling, consuming progress maintaining and other effortful work inside, leaving a callback interface to end user to implement which will be executed on message arrival.
+  Push consumer, on the other hand, encapsulates message pulling, consuming progress and maintaining other work inside, leaving a callback interface to end user to implement which will be executed on message arrival.
 
 ## Consumer Group
 
 Similar to previously mentioned producer group, consumers of the exactly same role are grouped together and named **Consumer Group**. 
 
 Consumer Group is a great concept with which achieving goals of load-balance and fault-tolerance, in terms of message consuming, is super easy. 
 
-**Warning**: consumer instances of a consumer group **must** have exactly same topic subscription(s).
+**Warning**: consumer instances of a consumer group **must** have exactly the same topic subscription(s).
 
 # Topic
 
-Topic is a category to which producers deliver messages and from which consumers pull messages. Topics have very loose relation with producers and consumers. Specifically, a topic may have zero, one or multiple producers that sends messages to it; conversely, a producer can sends messages of different topics. In consumer's view, a topic may be subscribed by zero, one or multiple consumer groups; and a consumer group, in the same paradigm, may subscribe one or multiple topics as long as instances of this group keep their subscription consistent as emphasized in the previous section. 
+Topic is a category in which producers deliver messages and consumers pull messages. Topics have very loose relationship with producers and consumers. Specifically, a topic may have zero, one or multiple producers that sends messages to it; conversely, a producer can send messages of different topics. In consumer's perspective, a topic may be subscribed by zero, one or multiple consumer groups. And a consumer group, similarly, may subscribe to one or more topics as long as instances of this group keep their subscription consistent.
 
 # Message
 
-Message is the envelope of your information to deliver. A message must be specified with a topic, which can be interpreted as address of your letter to mail to. A message may also have an optional tag set. Extra key-value pairs may also be included. For example, you may set a business key for your message and look up the message on broker server to diagnose issues during development.
+Message is the information to be delivered. A message must have a topic, which can be interpreted as address of your letter to mail to. A message may also have an optional tag and extra key-value pairs. For example, you may set a business key to your message and look up the message on a broker server to diagnose issues during development.
 
 ## Message Queue
 
-Topic, internally, is logically partitioned into one or more sub-topics. We call these sub-topics "message queues". This concept plays a major role in implementing valuable features, including fail-over, maximum concurrency, etc. 
+Topic is partitioned into one or more sub-topics, "message queues".
 
 ## Tag
 
-Tag, which can be thought as sub-topic, provides an extra flexibility for user. Through introducing tag,  messages with different purposes from the same business module may have the same topic yet different tag. It would be helpful to keep your code clean and coherent.
+Tag, in other words sub-topic, provides extra flexibility to users. With tag, messages with different purposes from the same business module may have the same topic and different tag. Tags would be helpful to keep your code clean and coherent, and tags also can facilitate the query system RocketMQ provides.
 
 ## Broker
 
-Broker is the major role of the RocketMQ system. It receives messages sent from producers, store them and being prepared to serve pull requests from consumers. It also stores message consuming related meta data, including consumer groups, consuming progress offsets and topic / queue info.
+Broker is a major component of the RocketMQ system. It receives messages sent from producers, store them and prepare to handle pull requests from consumers. It also stores message related meta data, including consumer groups, consuming progress offsets and topic / queue info.
 
 # Name Server
 
-Name server serves as the routing information provider. Producer/Consumer clients look up topics to find broker list to read from and write to.
+Name server serves as the routing information provider. Producer/Consumer clients look up topics to find the corresponding broker list.
 
 # Message Model
 
@@ -89,7 +89,7 @@ Consuming messages orderly means messages are consumed the same order they are s
 
 * Concurrently
 
-When consuming concurrently, maximum concurrency of message consuming is only limited by thread pool specified for each consumer client.
+When consuming messages concurrently, maximum concurrency of message consuming is only limited by thread pool specified for each consumer client.
 
 **Warn**: Message order is no longer guaranteed in this mode.
 

_docs/04-cli-admin-tool.md

@@ -15,15 +15,15 @@ Make sure you have walked through [Quick Start](/docs/quick-start/) and [Core Co
 
 # How To Get it
 
-The admin tool is shipped along with RocketMQ. Either you download a pre-built binary version or build from source by yourself, you already have it.
+The admin tool is shipped along with RocketMQ. Whether you download a pre-built binary version or build from source by yourself, you have the tool with the package.
 
-In case you don't have source code, the [rocketmq-tools module](https://github.com/apache/incubator-rocketmq/tree/master/tools) contains its source code.
+If you want to look at the source code, please refer to [rocketmq-tools module](https://github.com/apache/incubator-rocketmq/tree/master/tools)
 
 # How to use
 
-The Admin Tool is very easy to use. Here, for demonstration purpose, *nix environment is assumed.
+The Admin Tool is very user friendly. Here, for demonstration purpose, *nix environment is assumed.
 
-Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the following help menu pops out.
+Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the following help menu.
 
     The most commonly used mqadmin commands are:
        updateTopic          Update or create topic
@@ -34,21 +34,21 @@ Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the f
        updateTopicPerm      Update topic perm
        topicRoute           Examine topic route info
        topicStatus          Examine topic Status info
-       topicClusterList     get cluster info for topic
+       topicClusterList     Get cluster info for topic
        brokerStatus         Fetch broker runtime status data
        queryMsgById         Query Message by Id
        queryMsgByKey        Query Message by Key
        queryMsgByUniqueKey  Query Message by Unique key
        queryMsgByOffset     Query Message by offset
        queryMsgByUniqueKey  Query Message by Unique key
        printMsg             Print Message Detail
-       sendMsgStatus        send msg to broker.
+       sendMsgStatus        Send msg to broker.
        brokerConsumeStats   Fetch broker consume stats data
        producerConnection   Query producer's socket connection and client version
        consumerConnection   Query consumer's socket connection, client version and subscription
        consumerProgress     Query consumers's progress, speed
        consumerStatus       Query consumer's internal data structure
-       cloneGroupOffset     clone offset from other group.
+       cloneGroupOffset     Clone offset from other group.
        clusterList          List all of clusters
        topicList            Fetch all topic list from name server
        updateKvConfig       Create or update KV config.
@@ -62,7 +62,7 @@ Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the f
        statsAll             Topic and Consumer tps stats
        syncDocs             Synchronize wiki and issue to github.com
        allocateMQ           Allocate MQ
-       checkMsgSendRT       check message send response time
+       checkMsgSendRT       Check message send response time
        clusterRT            List All clusters Message Send RT
 
     See 'mqadmin help <command>' for more information on a specific command.

_docs/05-cluster-deployment.md

@@ -22,7 +22,7 @@ Name server follows share-nothing design paradigm. Brokers send heartbeat data t
 
 # Broker
 
-Brokers can be divided into two categories according to their roles: master and slave. Master brokers can read and write while slave brokers can only read messages replicated from master. Master brokers have brokerId=0; brokerId of slave is non-zero. 
+Brokers can be divided into two categories according to their roles: master and slave. Master brokers can read and write while slave brokers can only read messages replicated from master. Master brokers have brokerID=0; brokerID of slave is non-zero.
 
 Brokers may also be grouped by the brokerName property. Slave brokers find their master through brokerName. One master broker along with zero, one or multiple slave brokers is called a broker set.