In response to comments from Chen Xi

doc/howto/dev/build_cn.md

@@ -23,13 +23,17 @@
    cd paddle; docker build -t paddle:dev .
    ```
 
+   请注意这个命令结尾处的 `.`；它表示 `docker build` 应该读取当前目录下的 [`Dockerfile`文件](https://github.com/PaddlePaddle/Paddle/blob/develop/Dockerfile)，按照其内容创建一个名为 `paddle:dev` 的 Docker image，并且把各种开发工具安装进去。
+
 3. 编译
 
+   以下命令启动一个 Docker container 来执行 `paddle:dev` 这个 Docker image，同时把当前目录（源码树根目录）映射为 container 里的 `/paddle` 目录，并且运行 `Dockerfile` 描述的默认入口程序 [`build.sh`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build.sh)。这个脚本调用 `cmake` 和 `make` 来编译 `/paddle` 里的源码，结果输出到 `/paddle/build`，也就是本地的源码树根目录里的 `build` 子目录。
+
    ```bash
    docker run -v $PWD:/paddle paddle:dev
    ```
 
-   这个命令编译出一个 CUDA-enabled 版本。所有二进制文件会被写到本机的 `./build` 目录，而不是写到 Docker container 里。如果我们只需要编译一个只支持 CPU 的版本，可以用
+   上述命令编译出一个 CUDA-enabled 版本。如果我们只需要编译一个只支持 CPU 的版本，可以用
 
    ```bash
    docker run -e WITH_GPU=OFF -v $PWD:/paddle paddle:dev
@@ -57,7 +61,7 @@
 
 - Docker 还是虚拟机？
 
-  有人用虚拟机来类比 Docker。需要强调的是：Docker 不会虚拟任何硬件，Docker container 里运行的编译工具实际上都是在本机的 CPU 和操作系统上直接运行的，性能和把编译工具安装在本机运行基本一样。
+  有人用虚拟机来类比 Docker。需要强调的是：Docker 不会虚拟任何硬件，Docker container 里运行的编译工具实际上都是在本机的 CPU 和操作系统上直接运行的，性能和把编译工具安装在本机运行一样。
 
 - 为什么用 Docker?
 
@@ -73,10 +77,6 @@
 
   理解 Docker 并不难，大概花十分钟看一下[这篇文章](https://zhuanlan.zhihu.com/p/19902938)。这可以帮您省掉花一小时安装和配置各种开发工具，以及切换机器时需要新安装的辛苦。别忘了 PaddlePaddle 更新可能导致需要新的开发工具。更别提简化问题复现带来的好处了。
 
-- Docker 需要 sudo
-
-  如果用自己的电脑开发，自然也就有管理员权限（sudo）了。如果用公用的电脑开发，需要请管理员安装和配置好 Docker。此外，PaddlePaddle 项目在努力开始支持其他不需要 sudo 的集装箱技术，比如 rkt。
-
 - 我可以用 IDE 吗？
 
   当然可以，因为源码就在本机上。IDE 默认调用 make 之类的程序来编译源码，我们只需要配置 IDE 来调用 Docker 命令编译源码即可。
@@ -95,6 +95,12 @@
 
   是的。我们的 Docker image 运行一个 [Bash 脚本](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build.sh)。这个脚本调用 `make -j$(nproc)` 来启动和 CPU 核一样多的进程来并行编译。
 
-- Docker on Windows/MacOS？
+## 可能碰到的问题
+
+- Docker 需要 sudo
+
+  如果用自己的电脑开发，自然也就有管理员权限（sudo）了。如果用公用的电脑开发，需要请管理员安装和配置好 Docker。此外，PaddlePaddle 项目在努力开始支持其他不需要 sudo 的集装箱技术，比如 rkt。
+
+- 在 Windows/MacOS 上编译很慢
 
   Docker 在 Windows 和 MacOS 都可以运行。不过实际上是运行在一个 Linux 虚拟机上。可能需要注意给这个虚拟机多分配一些 CPU 和内存，以保证编译高效。具体做法请参考[这个issue](https://github.com/PaddlePaddle/Paddle/issues/627)。

doc/howto/dev/build_en.md

@@ -7,7 +7,7 @@ To contribute to PaddlePaddle, you need
 1. A computer -- Linux, BSD, Windows, MacOS, and
 1. Docker.
 
-Nothing else.  Not even Python and GCC, because you can install all build tools into a Docker image.
+Nothing else.  Not even Python and GCC, because you can install all build tools into a Docker image.  We run all the tools by running this image.
 
 ## General Process
 
@@ -17,19 +17,23 @@ Nothing else.  Not even Python and GCC, because you can install all build tools
    git clone https://github.com/paddlepaddle/paddle
    ```
 
-2. Install build tools.
+2. Install build tools into a Docker image.
 
    ```bash
    cd paddle; docker build -t paddle:dev .
    ```
 
+   Please be aware of the `.` at the end of the command, which refers to the [`./Dockerfile` file](https://github.com/PaddlePaddle/Paddle/blob/develop/Dockerfile).  `docker build` follows instructions in this file to create a Docker image named `paddle:dev`, and installs building tools into it.
+
 3. Build from source.
 
+   This following command starts a Docker container that executes the Docker image `paddle:dev`, mapping the current directory to `/paddle/` in the container, and runs the default entry-point [`build.sh`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build.sh) as specified in the Dockefile.  `build.sh` invokes `cmake` and `make` to build PaddlePaddle source code, which had been mapped to `/paddle`, and writes outputs to `/paddle/build`, which maps to `build` in the current source directory on the computer.
+
    ```bash
    docker run -v $PWD:/paddle paddle:dev
    ```
 
-   This builds a CUDA-enabled version and writes all binary outputs to directory `./build` of the local computer, other than the Docker container.  If we want to build only the CPU part, we can type
+   Above command builds a CUDA-enabled version.  If we want to build a CPU-only version, we can type
 
    ```bash
    docker run -e WITH_GPU=OFF -v $PWD:/paddle paddle:dev
@@ -57,25 +61,21 @@ Nothing else.  Not even Python and GCC, because you can install all build tools
 
 - Docker or virtual machine?
 
-  Some people compare Docker with VMs, but Docker doesn't virtualize any hardware, and it doesn't run a guest OS.
+  Some people compare Docker with VMs, but Docker doesn't virtualize any hardware nor running a guest OS, which means there is no compromise on the performance.
 
 - Why Docker?
 
-  Using a Docker image of build tools standardize the building environment, and easier for others to reproduce your problem, if there is any, and help.
+  Using a Docker image of build tools standardizes the building environment, which makes it easier for others to reproduce your problems and to help.
 
   Also, some build tools don't run on Windows or Mac or BSD, but Docker runs almost everywhere, so developers can use whatever computer they want.
 
-- Can I don't use Docker?
+- Can I choose not to use Docker?
 
-  Sure, you don't have to install build tools into a Docker image; instead, you can install them onto your local computer.  This document exists because Docker would make the development way easier.
+  Sure, you don't have to install build tools into a Docker image; instead, you can install them in your local computer.  This document exists because Docker would make the development way easier.
 
 - How difficult is it to learn Docker?
 
-  It takes you ten minutes to read [an introductory article](https://docs.docker.com/get-started) and saves you more than one hour to install all required build tools, configure them, and upgrade them when new versions of PaddlePaddle require some new tools.
-
-- Docker requires sudo
-
-  An owner of a computer has the administrative privilege, a.k.a., sudo.  If you use a shared computer for development, please ask the administrator to install and configure Docker.  We will do our best to support rkt, another container technology that doesn't require sudo.
+    It takes you ten minutes to read [an introductory article](https://docs.docker.com/get-started) and saves you more than one hour to install all required build tools, configure them, especially when new versions of PaddlePaddle require some new tools.  Not even to mention the time saved when other people trying to reproduce the issue you have.
 
 - Can I use my favorite IDE?
 
@@ -93,8 +93,14 @@ Nothing else.  Not even Python and GCC, because you can install all build tools
 
 - Does Docker do parallel building?
 
-  Our building Docker image runs a [Bash script](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build.sh), which calls `make -j$(nproc)` to starts as many processes as the number of your processors.
+  Our building Docker image runs a [Bash script](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/scripts/docker/build.sh), which calls `make -j$(nproc)` to starts as many processes as the number of your CPU cores.
+
+## Some Gotchas
+
+- Docker requires sudo
+
+  An owner of a computer has the administrative privilege, a.k.a., sudo, and Docker requires this privilege to work properly.  If you use a shared computer for development, please ask the administrator to install and configure Docker.  We will do our best to support rkt, another container technology that doesn't require sudo.
 
-- Docker on Windows/MacOS?
+- Docker on Windows/MacOS builds slowly
 
   On Windows and MacOS, Docker containers run in a Linux VM.  You might want to give this VM some more memory and CPUs so to make the building efficient.  Please refer to [this issue](https://github.com/PaddlePaddle/Paddle/issues/627) for details.