[ROCKETMQ-216] - Website polish closes apache#14

_data/navigation.yml

@@ -19,10 +19,10 @@ main:
 docs:
  - title: User Guide
  children:
- - title: "Quick Start"
- url: /docs/quick-start/
  - title: "Why RocketMQ"
  url: /docs/motivation/
+ - title: "Quick Start"
+ url: /docs/quick-start/
  - title: "Simple Example"
  url: /docs/simple-example/
  - title: "Order Example"

_docs/01-quick-start-guide.md

@@ -5,7 +5,7 @@ excerpt: "How to quickly install and setup Apache RocketMQ."
 modified: 2016-12-29T15:01:43-04:00
 ---
 
-This quick start guide is to give detailed instructions, helping you setup RocketMQ messaging system on a single local machine and send/receive the very first message.
+This quick start guide is a detailed instruction of setting up RocketMQ messaging system on a local machine and sending/receiving messages.
 
 {% include toc %}
 
@@ -42,12 +42,11 @@ This quick start guide is to give detailed instructions, helping you setup Rocke
  > tail -f ~/logs/rocketmqlogs/broker.log 
  The broker[%s, 172.30.30.233:10911] boot success...
 ```
- you may need to pay attention to the broker ip, for that the broker will not use the loopback network interface, So you should make sure you have connected to other network.
-
+
 
 # Send & Receive Messages
 
-Before sending/receiving messages, we need to tell clients where name servers are located. RocketMQ provides multiple ways to achieve this. For simplicity, we use environment variable `NAMESRV_ADDR`
+Before sending/receiving messages, we need to tell clients the location of name servers. RocketMQ provides multiple ways to achieve this. For simplicity, we use environment variable `NAMESRV_ADDR`
 
 ```shell
  > export NAMESRV_ADDR=localhost:9876

_docs/02-motivation.md

@@ -4,19 +4,19 @@ permalink: /docs/motivation/
 modified: 2016-12-16T15:01:43-04:00
 ---
 
-In the early stages, we constructed our distributed messaging middleware on the basis of ActiveMQ 5.x(less than 5.3). Our international business uses it for async communication, search, social network activity stream, data pipeline, even in our trade order process. As our trade business throughput rises more and more inconceivably, pressure originating from our messaging cluster also become more and more obvious.
+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.
 
 {% include toc %}
 
 # Why RocketMQ ?
 
-Based on our observations and research, with more and more queues and virtual topics in use, ActiveMQ IO module becomes a bottleneck. In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as 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 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.
 
-In this context, we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss. We also created a cornerstone product based on RocketMQ, a Platform as a Service (PaaS) product named the
-[Alibaba Cloud Platform](https://intl.aliyun.com/). Today, more than 100 companies are using the RocketMQ open source version in their business solutions. We believe RocketMQ can benefit more people, so we would like to share it around the world.
+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/).
 
 
-The following are some different design between RocketMQ, ActiveMQ and Kafka（They are the apache's most popular messaging solutions according to [awesome-java](https://github.com/akullpp/awesome-java)):
+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)):
 
 # RocketMQ vs. ActiveMQ vs. Kafka
 

_docs/04-cli-admin-tool.md

@@ -17,7 +17,7 @@ Make sure you have walked through [Quick Start](/docs/quick-start/) and [Core Co
 
 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.
 
-In case you have source code, the [rocketmq-tools module](https://github.com/apache/incubator-rocketmq/tree/master/tools) contains its source code.
+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.
 
 # How to use
 

_docs/07-frequently-asked-questions.md

@@ -3,20 +3,20 @@ title: "Frequently Asked Questions"
 permalink: /docs/faq/
 modified: 2016-12-27T15:18:43-04:00
 ---
-The following questions are frequently asked with regard to the RocketMQ project in general. If you have further questions, make sure to consult the documentation or ask the community.
+The following questions are frequently asked with regard to the RocketMQ project in general.
 
 ## General
-### 1. Why create rocketmq project instead of selecting other products?
-In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability. So we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss.
+### 1. Why did we create rocketmq project instead of selecting other products?
+Please refer to [Why RocketMQ](/docs/motivation/)
 
 ### 2. Do I have to install other softewares, such as zookeeper, to use RocketMQ?
-No. RocketMQ can run without any other softeware, you can run broker server and name server indepentently. Aslo, the topic can be created by using command, such as sh mqadmin updatetopic etc. After creating successfully, you enjoy yourself with RocketMQ.
+No. RocketMQ can run independently.
 
 ## Usage
 ### 1. Where does the newly created Consumer ID start consuming messages?
 
-1. If the topic sends a message within three days, then the consumer start consume message from the first message saved in the server.
-2. If the topic sends a message in three days ago, the consumer start consume message from the latest message in the server, in other words, starting to consume the message queue tail.
+1. If the topic sends a message within three days, then the consumer start consuming messages from the first message saved in the server.
+2. If the topic sends a message three days ago, the consumer start consuming messages from the latest message in the server, in other words, starting from the tail of message queue.
 3. If such consumer is the second reboot, then start to consumer message from the last consumption location.
 
 ### 2. How to reconsume message when consumption fails?

_docs/12-rmq-batch-example.md

@@ -7,23 +7,16 @@ modified: 2017-04-24T15:01:43-04:00
 
 {% include toc %}
 
-#### When to use batch
-Batch is not for packaging but improving performance of small messages. So the messages of the same batch should act the same role, no more effort should be taken to split the batch.
-No split has another important advantage, messages of the same batch should be sent atomically, that is all successfully or all unsuccessfully, of which the importance is self-evident.
-So performance and atomicity are the original intentions, which will reflect on the usage constraints. 
-That is to say, if you want to improve performance for small messages or to send messages atomically, batch is a nice solution for you.
-#### Usage constraints
-Performance and atomicity are worth the following constraints:
-messages of the same batch should have:
+### Why batch?
+Sending messages in batch improves performance of delivering small messages. 
 
-1. same topic: If they belong to different topics(internally the queues), then may be sent to different brokers, which will against atomicity.
-2. same waitStoreMsgOK: also differences will against atomicity.
-3. no delay level: If we care about the delay level, we need to decode the internal properties of every message, which will cause much performance loss.
+### Usage constraints
+Messages of the same batch should have: same topic, same waitStoreMsgOK and no schedule support.
 
-And the most important, the total size, that is the sum of size of each message in one batch, should be no more than 1M.
+Besides, the total size of the messages in one batch should be no more than 1MiB.
 
-#### How to use batch
-If you just send several small messages in a time and do not need to worry about the size limit, it is easy to use batch:
+### How to use batch
+If you just send messages of no more than 1MiB at a time, it is easy to use batch:
 
 ```java
 String topic = "BatchTest";
@@ -39,8 +32,8 @@ try {
 }
 
 ```
-#### Split into lists
-The complexity only grow when you send large batch and you may not sure if it exceeds the size limit (1M).
+### Split into lists
+The complexity only grow when you send large batch and you may not sure if it exceeds the size limit (1MiB).
 
 At this time, you'd better split the lists:
 
@@ -98,4 +91,4 @@ while (splitter.hasNext()) {
  //handle the error
  }
 }
-```
+```

_docs/13-rmq-broadcasting-example.md

@@ -7,60 +7,57 @@ modified: 2017-04-24T15:01:43-04:00
 
 {% include toc %}
 
-#### What is Broadcasting
-Broadcasting is when sending a meeage to a topic,all subscribers of the topic will receive the message even if they are in the same consumer group.If you want all subscribers in a group receive all the messages in a topic,broadcasting is a good choice.
+### What is broadcasting
+Broadcasting is sending a message to all subscribers of a topic. If you want all subscribers receive messages about a topic, broadcasting is a good choice.
 
-#### How to use
-
-##### First,Produce message as before
+### Producer example
 
 ```java
-DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");
-
-producer.start();
+public class BroadcastProducer {
+ public static void main(String[] args) throws Exception {
+ DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");
+ producer.start();
 
-for (int i = 0; i < 10000000; i++){
- try {
- {
+ for (int i = 0; i < 100; i++){
  Message msg = new Message("TopicTest",
  "TagA",
  "OrderID188",
  "Hello world".getBytes(RemotingHelper.DEFAULT_CHARSET));
  SendResult sendResult = producer.send(msg);
  System.out.printf("%s%n", sendResult);
  }
-
- } catch (Exception e) {
- e.printStackTrace();
+ producer.shutdown();
  }
 }
-producer.shutdown();
 ```
 
-##### Second,Consume message in Broadcast mode
+### Consumer example
 
 ```java
-DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("please_rename_unique_group_name_1");
+public class BroadcastConsumer {
+ public static void main(String[] args) throws Exception {
+ DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("example_group_name");
 
-consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
+ consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
 
-//set to broadcast mode
-consumer.setMessageModel(MessageModel.BROADCASTING);
+ //set to broadcast mode
+ consumer.setMessageModel(MessageModel.BROADCASTING);
 
-consumer.subscribe("TopicTest", "TagA || TagC || TagD");
+ consumer.subscribe("TopicTest", "TagA || TagC || TagD");
 
-consumer.registerMessageListener(new MessageListenerConcurrently() {
+ consumer.registerMessageListener(new MessageListenerConcurrently() {
 
- @Override
- public ConsumeConcurrentlyStatus consumeMessage(List<MessageExt> msgs,
- ConsumeConcurrentlyContext context) {
- System.out.printf(Thread.currentThread().getName() + " Receive New Messages: " + msgs + "%n");
- return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
- }
-});
+  @Override
+  public ConsumeConcurrentlyStatus consumeMessage(List<MessageExt> msgs,
+  ConsumeConcurrentlyContext context) {
+  System.out.printf(Thread.currentThread().getName() + " Receive New Messages: " + msgs + "%n");
+  return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
+  }
+ });
 
-consumer.start();
-System.out.printf("Broadcast Consumer Started.%n");
+ consumer.start();
+ System.out.printf("Broadcast Consumer Started.%n");
+ }
+}
 ```
 
-Enjoy it.

_docs/14-rmq-deployment.md

@@ -14,14 +14,14 @@ Before starting this section, make sure you have read Quick Start section, in wh
 
 #### Production-ready Deployment
 ##### Name Server
-To ensure the cluster can still operate normally when one instance crashes, two or more name server instances are recommended. As long as there is at least one name server instance alive, the whole cluster remains serving.
+To ensure the cluster can still operate normally when one instance crashes, two or more name server instances are recommended. As long as there is one name server instance alive, the whole cluster remains in service.
 
-Name server follows share-nothing design paradigm. Brokers send heartbeat data to all name servers. Producers and consumers may query meta data from any one of name servers available while sending / consuming messages.
+Name server follows the share-nothing design paradigm. Brokers send heartbeat data to all name servers. Producers and consumers may query meta data from any of name servers available while sending / consuming messages.
 
 #### Broker
 Brokers can be divided into two categories according to their roles: master and slave. Master brokers provide RW access while slave brokers only accept read access.
 
-To deploy a high-availability RocketMQ cluster which has no single point of failure, a series of broker sets should be deployed. One broker set contains one master with brokerId set to 0 and several slaves with non-zero brokerIDs. All of the brokers in one set have the same brokerName. In serious scenarios, we should have at least two brokers in one broker set. Each topic resides in two or more brokers.
+To deploy a high-availability RocketMQ cluster which has no single point of failure, a series of broker sets should be deployed. A broker set contains one master with brokerId set to 0 and several slaves with non-zero brokerIDs. All of the brokers in one set have the same brokerName. In serious scenarios, we should have at least two brokers in one broker set. Each topic resides in two or more brokers.
 
 ### Configuration
 When deploying a RocketMQ cluster, below configurations should be taken into consideration.
@@ -111,11 +111,11 @@ usage: mqadmin clusterList [-h] [-i <arg>] [-m] [-n <arg>]
 ```
 
 ### Replication mode
-With the purpose to guarantee that any successfully published message will not be lost, RocketMQ provides a Replication mode to gain stronger durability and higher availability with two replication way: Sync & Async.
+To guarantee any successfully published message won't be lost, RocketMQ provides a Replication mode to gain stronger durability and higher availability with two replication way: Sync & Async.
 
 ##### Replication: Sync / Async Broker
 
-Similar to many replication system, sync brokers await until commit log is replicated to the slave before acknowledging. Async brokers, instead, return immediately after messages are processed on master.
+Like many replication system, sync brokers wait until commit log is replicated to the slave before acknowledging. Async brokers, instead, return immediately after messages are processed on master.
 
 ##### How to configure
 There are three pre-built configurations shipped with the distribution of RocketMQ under conf folder for your reference: