- 技术文档写得好不好，不是看词汇多华丽，而是看读者能不能一步一步照着做完还不出错——Google 的技术文档风格指南把这个原则放在最前面。
- 核心是第二人称（"you"）+ 主动语态，让读者随时清楚「是谁在执行这个动作」。
- 条件要写在指令前面，不是后面——这是容易被中文语序习惯带偏的一点。
- 学完能写出一段结构清晰、读者不会中途卡住的操作说明/用户指南段落。
重点内容
写作框架
- 开头：一句话说明这一节要完成什么任务/解决什么问题，让读者判断「这是我要找的内容」。
- 前置条件（Prerequisites）：列出开始前需要具备的东西（权限、安装好的软件、版本号），条件永远写在对应指令之前，不要写成「做完 X 之后你需要先有 Y」。
- 步骤（Numbered steps）：有顺序的操作用编号列表，没有顺序关系的选项/参数用项目符号列表。
- 结尾：确认结果（"You should now see..."）或指向下一步。
范文 / 模板句型
- 条件前置："If you haven't installed the CLI, install it before continuing."（如果你还没安装 CLI，请先安装再继续。）
- 第二人称+主动语态："You can restart the service by running the following command."（你可以通过运行以下命令重启该服务。）
- 步骤衔接："Once the installation completes, open the configuration file and update the API key."（安装完成后，打开配置文件并更新 API 密钥。）
- 确认结果："You should now see a confirmation message in the terminal."（此时你应该会在终端看到一条确认消息。）
- 语气把控："This guide walks you through setting up your first project."（本指南将带你完成第一个项目的设置。）
常见错误
马来西亚华人写这类文体常见的错误：
❌ "The button should be clicked to save the file."
✅ "Click the button to save the file." （容易套用被动语态显得「正式」，但风格指南明确要求用主动语态，让读者一眼看出该由谁执行动作。）
❌ "After you complete step 3, make sure you have Python 3.8 or higher installed."
✅ "Before you begin, make sure you have Python 3.8 or higher installed. Then complete step 3." （条件写在指令后面，读者读到一半才发现自己缺东西，得回头重做——条件永远要前置。）
❌ 混用 "we" / "the user" / "you" 指称读者，一段话里人称跳来跳去。
✅ 全文统一用 "you" 称呼读者。 （风格指南明确建议 "you" 优先于 "we"，人称跳动会让读者分心去猜「这是指谁」。）
Sources
Blog / Website：