1 files changed, 158 insertions, 52 deletions
diff --git a/docs/zh-cn/newbs_getting_started.md b/docs/zh-cn/newbs_getting_started.md
index 596ab78f7f..7ca9871aa7 100644
--- a/docs/zh-cn/newbs_getting_started.md
+++ b/docs/zh-cn/newbs_getting_started.md
@@ -1,93 +1,183 @@
-# 介绍
+# 配置环境
 
-你的电脑键盘里面包含一个处理器, 这个处理器和你电脑里面的不太一样。这个处理器负责运行一些特殊的软件，这些软件可以监测按钮按下并将按钮处于按下还是释放状态的数据发送出去。QMK就是这样一种软件，即监测按钮被按下并发送这样的信息到作为主机的计算机上。当你创建了你的布局, 你也就创建了你的键盘运行的的可执行程序。
+<!---
+  original document: 0.15.12:docs/newbs_getting_started.md
+  git diff 0.15.12 HEAD -- docs/newbs_getting_started.md | cat
+-->
 
-QMK试图通过使简单的事情变得更简单，使使不可能成为可能来把大量的权力交给你。你不需要懂如何通过程序创建强大的布局——你只需要遵循简单的语法规则。
+构建键映射前，有一些必须安装配置的构建工具，但无论你要编译多少个固件，这一步只需要做一次。
 
-# 新手上路
+## 1. 必备工具
 
-在你能创建布局前,你要安装一些软件来建立你的开发环境。无论你想编译多少固件，这个操作都只需要进行一次。
+首先需要确保一些基本的软件配备。
 
-如果您更喜欢图形化界面, 请考虑使用在线工具[QMK配置器](https://config.qmk.fm)。 请参考 [使用在线GUI构建您的第一个固件](newbs_building_firmware_configurator.md)。
+* [文本编辑器](zh-cn/newbs_learn_more_resources.md#text-editor-resources)
+  * 你需要至少一个能编辑常规文本的软件。系统自带的编辑器通常不会如实保存（会做一些额外的处理，如回车），所以选择编辑器时需要留意。
+* [QMK工具箱(可选)](https://github.com/qmk/qmk_toolbox)
+  * 在Windows及macOS上可用的图形程序，用于编辑及调试你的键盘
 
+?> 如果你没有Linux/Unix命令行使用经验，有些基本概念需要先学习一下。[这些资料](zh-cn/newbs_learn_more_resources.md#command-line-resources)是个使用QMK很好的参考。
 
-## 下载软件
+## 2. 准备构建环境 :id=set-up-your-environment
 
-### 文本编辑器
+我们已经尽力让QMK易于配置了，你只要准备好Linux或Unix环境，剩余的交给QMK来安装。
 
-你需要一个可以编辑 **纯文本** 文件的程序。在Windows上你可以用Notepad, 在Linux上使用gedit，这两个都是简单又实用的文本编辑工具。 在macOS上, 请小心使用 “文本编辑” 这个默认软件: 如果你不明确的选择_格式_菜单中的 _制作纯文本_ 的话文本将不会被保存为纯文本。
+<!-- tabs:start -->
 
-你也可以下载并安装一个专用编辑器 [Sublime Text](https://www.sublimetext.com/) 或 [VS Code](https://code.visualstudio.com/)。 这大概是跨平台的最好方法了, 这些编辑器是专门为了编辑代码设计的。
+### ** Windows **
 
-?>搞不清用哪种编辑器? Laurence Bradford 写了篇关于编辑器选择的文章 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/)。
+QMK有维护一套基于MSYS2的软件包，所有命令行程序和依赖都是齐备的。通过 `QMK MSYS` 快捷命令可以快速启动开发环境。
 
-### QMK 工具箱
+#### 依赖项
 
-QMK 工具箱 是一种可选的Windows和macOS下的图形化工具，它可以对你的定制键盘进行编程和调试。你可能会发现它就是你能简单的刷新你的键盘固件并查看调试信息的稀世珍宝。
+需安装[QMK MSYS](https://msys.qmk.fm/)，最新版在[这里](https://github.com/qmk/qmk_distro_msys/releases/latest)。
 
-[在这里下载最新发布版本](https://github.com/qmk/qmk_toolbox/releases/latest)
+此外，如果想自行安装MSYS2环境，下面给出了具体的步骤。
 
-* Windows用户: `qmk_toolbox.exe` (绿色版) 或 `qmk_toolbox_install.exe` (安装版)
-* macOS用户: `QMK.Toolbox.app.zip` (绿色版) or `QMK.Toolbox.pkg` (安装版)
+<details>
+  <summary>自行安装</summary>
 
-## 建立你的环境
+?> 若决定使用 `QMK MSYS`，请跳过此节.
 
-我们为了使QMK环境变得更容易建立已竭尽所能。你只需要准备Linux 或 Unix 环境, 然后让QMK安装剩余部分。
+#### 依赖项
 
-?> 如果你从未使用过Linux/Unix的命令行,有一些你需要学习的基础概念和命令，以下资料将教会您使用QMK环境的必要能力:<br>
-[必会Linux命令](https://www.guru99.com/must-know-linux-commands.html)<br>
-[一些基本的Unix命令](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
+遵循 https://www.msys2.org 上的指引，安装MSYS2、Git和Python。
 
-### Windows
+在MSYS2安装完毕后，关闭所有的MSYS终端，启动新的MinGW 64-bit终端。
 
-你需要安装MSYS2和Git.
+!> **注意:** MinGW 64-bit 终端*不同于*安装包最后打开的MSYS终端，窗口标题应当是紫色的"MINGW64"而不是"MSYS"。具体的差异可以[参考这里](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems)。
 
-* 按照以下安装说明进行操作[MSYS2 主页](https://www.msys2.org)。
-* 关闭所有打开的MSYS2终端并打开新的MSYS2 MinGW 64-bit终端。
-* 使用以下命令安装Git: `pacman -S git`。
+执行如下命令：
 
-### macOS
+    pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip
 
-你需要安装Homebrew。按照以下说明进行操作 [Homebrew 主页](https://brew.sh)。
+#### 安装
 
-在Homebrew安装完成后, 继续 _同步QMK工程_. 这一步你将会通过运行一个脚本安装其他包。
+安装QMK命令行程序:
 
-### Linux
+    python3 -m pip install qmk
 
-你将需要安装Git.你很有可能已经安装,但若你尚未安装,可以使用以下命令进行安装:
+</details>
 
-* Debian / Ubuntu / Devuan: `apt-get install git`
-* Fedora / Red Hat / CentOS: `yum install git`
-* Arch: `pacman -S git`
+### ** macOS **
 
-?> 无论你使用哪种平台，Docker都可以是你的选择[点这里进一步了解](getting_started_build_tools.md#docker)
+QMK维护了一套Homebrew tap和formula以用于自动安装命令行程序及依赖项。
 
-## 同步QMK工程
+#### 依赖项
 
-当你建立Linux/Unix环境后,你就已经可以下载QMK了.下载时我们可以用Git来 "clone" QMK仓库. 打开一个终端或MSYS2 MinGW 窗口，在阅读剩余的指南时请保持窗口打开。在窗口里面运行以下两句命令:
+须先安装Homebrew，可以参考 https://brew.sh
 
-```shell
-git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
-cd qmk_firmware
-```
+#### 安装
+
+安装QMK命令行程序：
+
+    brew install qmk/qmk/qmk
+
+### ** Linux/WSL **
+
+?> **WSL用户注意**: 默认情况下，QMK仓库会被clone到home目录下，如果想指定其它目录，务必留意要放在WSL文件系统中（即，非 `/mnt` 目录下），否则文件读写会[非常慢](https://github.com/microsoft/WSL/issues/4197).
+
+#### 依赖项
+
+须安装Git及Python，通常你肯定已经有了，如果确实没有，请使用下面的方法尝试安装：
+
+* Debian / Ubuntu / Devuan: `sudo apt install -y git python3-pip`
+* Fedora / Red Hat / CentOS: `sudo yum -y install git python3-pip`
+* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git python-pip libffi`
+* Void: `sudo xbps-install -y git python3-pip`
+* Solus: `sudo eopkg -y install git python3`
+* Sabayon: `sudo equo install dev-vcs/git dev-python/pip`
+* Gentoo: `sudo emerge dev-vcs/git dev-python/pip`
+
+#### 安装
+
+安装QMK命令行程序：
+
+    python3 -m pip install --user qmk
+
+#### 社区提供的包
+
+有一些社区成员提供的包，可能版本会有落后或是功能不全的问题，如果你遇到了什么问题，请联系维护它的社区成员。
+
+Arch系环境下可以使用官方源安装命令行程序（在写这份文档时，有些依赖项被标记为可选的，其实不是）：
+
+    sudo pacman -S qmk
+
+也可以尝试AUR的 `qmk-git`：
+
+    yay -S qmk-git
+
+###  ** FreeBSD **
+
+#### 安装
+
+使用FreeBSD包安装QMK命令行程序：
+
+    pkg install -g "py*-qmk"
+
+请遵循安装后输出的指引操作进行配置（使用 `pkg info -Dg "py*-qmk"` 可以显示这份指引）。
+
+<!-- tabs:end -->
+
+## 3. 执行QMK配置 :id=set-up-qmk
+*译注：由于setup过程中需要从github clone依赖项，请先确保科学上网*
+
+<!-- tabs:start -->
 
-?> 如果您已经知道[如何使用GitHub](getting_started_github.md), 我们推荐您创建您自己的分支并克隆。 如果您不知道这是什么, 您完全可以忽略这句无关紧要的话。
+### ** Windows **
 
-QMK附带一个脚本，可帮助您设置剩余的所需内容.您可以通过输入此命令来运行它:
+安装QMK后，执行：
 
-    util/qmk_install.sh
+    qmk setup
 
-## 测试你的开发环境
+通常所有的询问回复 `y` 就行了。
 
-现在你的QMK环境已经建立完毕, 你可以为你的键盘创建固件了。开始试着创建键盘的默认固件吧。 你需要使用以下格式的命令创建固件:
+### ** macOS **
 
-    make <keyboard>:default
+安装QMK后，执行：
 
-比如, 制作一个Clueboard 66%的固件，需要用:
+    qmk setup
 
-    make clueboard/66/rev3:default
+通常所有的询问回复 `y` 就行了。
 
-当完成后你要看到一些回显，尾部如下:
+### ** Linux/WSL **
+
+安装QMK后，执行：
+
+    qmk setup
+
+通常所有的询问回复 `y` 就行了。
+
+?>**Debian及Ubuntu系环境须留意**:
+也许你会遇到 `bash: qmk: command not found` 错误，主要是因为Debian上的Bash 4.4版本引入的一个[bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)，`$HOME/.local/bin` 被从PATH环境变量中删除了，后续版本中这个问题已被修复。
+然而Ubuntu很挫地再次引入了这个bug[且没有修复](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562)。
+不过修复也很容易，在当前账户中执行：`echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc`
+
+###  ** FreeBSD **
+
+安装QMK后，执行：
+
+    qmk setup
+
+通常所有的询问回复 `y` 就行了。
+
+<!-- tabs:end -->
+
+?> QMK的home目录可以在安装时通过 `qmk setup -H <path>` 来指定，安装后也可以通过[命令行程序来配置](zh-cn/cli_configuration.md?id=single-key-example)`user.qmk_home`变量，可以通过 `qmk setup --help` 查看所有可用配置。
+
+?> 若你熟悉GitHub，[推荐阅读这份指引](zh-cn/getting_started_github.md)通过 `qmk setup <github_username>/qmk_firmware` 来clone你自己的fork。如果你看不懂这一段啥意思，忽略就是了。
+
+## 4. 测试你的构建环境
+
+QMK构建环境搭建完成，可以尝试构建一个键盘固件。使用以下指令格式，先试试编译默认提供的键映射：
+
+    qmk compile -kb <keyboard> -km default
+
+例如，要构建一个Clueboard 66%，就这样执行：
+
+    qmk compile -kb clueboard/66/rev3 -km default
+
+你应当能看到像这样的输出信息：
 
 ```
 Linking: .build/clueboard_66_rev3_default.elf                                                       [OK]
@@ -97,6 +187,22 @@ Checking file size of clueboard_66_rev3_default.hex
  * The firmware size is fine - 26356/28672 (2316 bytes free)
 ```
 
-# 创建你的布局
+## 5. 配置你的构建环境 (可选的)
+
+通过对默认配置的简单调整，QMK用起来会更有趣一些，我们来试试！
+
+大部分QMK新手手头只有一把键盘，可以通过 `qmk config` 命令将它设置为默认键盘，例如你想将 `clueboard/66/rev4` 设置为默认，可以这样：
+
+    qmk config user.keyboard=clueboard/66/rev4
+
+也可以调整默认的键映射名称。社区上大家常用自己的GitHub用户名，这也是我们推荐的做法。
+
+    qmk config user.keymap=<github_username>
+
+完成后，这些配置就不用管了，编译键盘固件就可以直接这样执行：
+
+    qmk compile
+
+# 制作你自己的键映射
 
-现在你可以创建属于你自己的布局了! 请移步 [构建你的第一个固件](newbs_building_firmware.md)来继续。
+万事俱备啦！请继续阅读[构建第一个固件](zh-cn/newbs_building_firmware.md).