技术写作与文档2021documentation.divio.com编辑精选
编写更好文档的框架
A Framework for Writing Better Documentation
导读
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。对写作者的价值在于：先想清楚这篇文档要让读者达成什么目标，再决定用什么写法，而不是把所有内容混在一篇文章里。
可以直接用的写作要点
- 01
动笔前先问「读者读完要能做什么」，用目标（学习／解决问题／查信息／理解原理）决定文档类型和写法。
- 02
不要把教程和参考混在一起写：教程要手把手带读者走通一条路，参考要能快速查到准确细节，混着写两边都做不好。
- 03
框架不必求全，发布说明等类型可以自己补充；重点是养成按「目标与结果」给文档分类的习惯。
- 04
卡壳时可以用「陈述—示例—解释」三步法：先给结论，再给例子，最后讲原因，能快速打破写作阻塞。
HN 评论精选
框架的核心贡献是让作者按读者目标给文档分类，不必拘泥于术语和是否覆盖全部类型。
我审阅过很多技术文档，这是我常推荐用来解释文档该如何组织的资源之一。这些观点在软件技术写作圈基本是共识，只是各人对每种类型的叫法略有不同，比如我用「概览」而不是「解释」。这个框架也不全面，像发布说明这类关键文档就没覆盖到。我认为 Divio 框架最大的突破，是让作者从「期望的目标和结果」来思考文档：学习导向、问题导向等等。
kaycebasques查看英文原文
I review a lot of technical software documentation. This is one of my go-to resources for explaining how docs should be organized. These ideas are generally accepted among software technical writers; you may just hear them use slightly different words for each doc type. E.g. I use "overview" instead of "explanation". I'll also mention that this framework isn't comprehensive; there are other types of critical documents that aren't explained here, such as release notes. I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc. Edit: I suppose you could argue that release notes fall under the category of reference-oriented, but when I look at the guidelines for reference docs it's clear that the Divio people were thinking about API references.
这套框架有清晰的传承脉络，是多年实践积累而非凭空提出。
这套思想的源头很大程度来自 Jacob Kaplan-Moss，他最早重构了 Django 文档，2009 年就写下了这些概念（链接：jacobian.org/series/great-documentation/）。Daniele Procida 在此基础上做了发展和体系化，形成了这个资源，它确实是我所知最好的文档写作资料。
ericholscher查看英文原文
A lot of the origin of this work is from Jacob Kaplan-Moss who did the original refactor of the Django documentation. He wrote up the concepts here in 2009: https://jacobian.org/series/great-documentation/ Daniele Procida built on this and formalized it through this resource, which is really amazing and definitely the best resource for writing docs that I know of.
Divio 指南可与具体项目的写作风格指南配合使用。
我一直在参与 Redux 核心文档的重写，其中包括从零写了几篇全新的完整教程。过程中我收集了不少文档写作建议的资料。我最喜欢的两份就是这份 Divio 文档写作指南和 Vue 的文档写作风格指南，都非常出色。
acemarke查看英文原文
I've been working on an ongoing rewrite for the Redux core docs [0], including writing a couple brand new comprehensive tutorials from scratch [1]. In the process, I collected a bunch of notes and resources on useful docs writing advice [2]. My two favorites by far are this Divio docs writing guide, and the Vue docs writing style guide [3]. Excellent resources! [0] https://github.com/reduxjs/redux/issues/3592 [1] https://redux.js.org/tutorials/index [2] https://github.com/reduxjs/redux/issues/3609 [3] https://v3.vuejs.org/guide/contributing/writing-guide.html
「陈述—示例—解释」三步法是打破写作阻塞的实用小技巧。
感谢分享，看起来是很棒的资源。多年前一位技术写作者教过我一个「SEE」方法，即陈述（statement）、示例（example）、解释（explanation）。我没找到过这个说法的出处，但对「让工程师先动起来」这类简单场景很有效，能帮人突破写作阻塞。它算不上覆盖所有文档类型的宏大理论。
miller_joe查看英文原文
This looks like a great resource, thank you for sharing. One trick I learned many moons ago from a tech writer was what he called the "SEE" method - statement, example, explanation. I've never found any references to it. I've found it effective for simple cases such as helping engineer's "just get started" to break writer's block. It's not a grand theory covering all doc types.
同类还值得读
写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选Diátaxis——技术文档编写的系统化方法
Diátaxis – A systematic approach to technical documentation authoring
Diátaxis 是一套把技术文档按「教程、操作指南、参考、解释」四类拆分的写作框架，核心是让每一篇文档只服务一种读者需求、只承担一种写作任务。
技术写作与文档2024 · 514 分 · 113 评4 条写作要点编辑精选