Diátaxis

A systematic approach to technical documentation authoring.

一套系统化的技术文档（documentation）写作方法。

Diátaxis is a way of thinking about and doing documentation.

Diátaxis 是一种思考文档、制作文档的方式。

Help translate Diátaxis into your language.

帮助把 Diátaxis 翻译成你的语言。

It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.

它对文档的内容、架构与形式给出明确主张——这些主张源自对文档用户需求的系统化理解。

Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation.

Diátaxis 识别出四种不同的需求，以及与之对应的四种文档形式——教程（tutorial）、操作指南（how-to guide）、技术参考（reference）与阐释（explanation）。

It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.

它把这四者放进一个系统化的关系里，并主张：文档本身就应当围绕这些需求的结构来组织。

Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).

Diátaxis 解决的是文档的内容问题（写什么）、文风问题（怎么写）与架构问题（如何组织）。

As well as serving the users of documentation, Diátaxis has value for documentation creators and maintainers.

除了服务文档的用户，Diátaxis 对文档的创作者与维护者同样有价值。

It is light-weight, easy to grasp and straightforward to apply. It doesn't impose implementation constraints.

它轻量、易懂、上手直接，也不强加任何实现层面的约束。

It brings an active principle of quality to documentation that helps maintainers think effectively about their own work.

它为文档带来一条主动的品质（quality）原则，帮助维护者有效地思考自己的工作。

The best way to get started with Diátaxis is by applying it after reading a brief primer: Start here.

入门 Diátaxis 最好的方式：读一篇简短的入门导引，然后直接上手应用——从这里开始。

These pages will help make immediate, concrete sense of the approach: Applying Diátaxis.

下面这些页面帮你立刻、具体地理解这套方法：应用 Diátaxis。

This section explores the theory and principles of Diátaxis more deeply, and sets forth the understanding of needs that underpin it: Understanding Diátaxis.

这一部分更深入地探讨 Diátaxis 的理论与原则，并阐明支撑它的那套需求理解：理解 Diátaxis。

Diátaxis is proven in practice. Its principles have been adopted successfully in hundreds of documentation projects.

Diátaxis 经受过实践检验，其原则已在数百个文档项目中被成功采用。

You don’t need to read everything on this website to make sense of Diátaxis, or to start using it in practice.

你不需要读完这个网站上的所有内容才能理解 Diátaxis，或者才能开始在实践中使用它。

In fact I recommend that you don’t.

事实上，我建议你不要那么做。

The best way to get started with Diátaxis is by applying it - to something, however small.

上手 Diátaxis 的最好方式就是去应用它——用在某件事上，无论多小都行。

Read this page for a brief primer.

读完本页，你就得到了一份简明入门。

Each section contains links to more in-depth material; refer to that when you need it - when you’re actually at work, or reflecting on the documentation problems you have encountered.

每一节都附有更深入材料的链接；需要时再去查阅——比如你真正在工作（work）时，或者在反思你遇到的文档（documentation）问题时。

The core idea of Diátaxis is that there are fundamentally four identifiable kinds of documentation, that respond to four different needs.

Diátaxis 的核心思想是：从根本上说，存在四种可辨识的文档类型，分别回应四种不同的需求（needs）。

The four kinds are: tutorials, how-to guides, reference and explanation.

这四种是：教程（tutorial）、操作指南（how-to guide）、参考（reference）和阐释（explanation）。

Each has a different purpose, and needs to be written in a different way.

每一种都有不同的目的，也需要用不同的方式来写。

A tutorial is a lesson, that takes a student by the hand through a learning experience.

教程是一堂课，它牵着学生的手走完一段学习体验。

A tutorial is always practical: the user does something, under the guidance of an instructor.

教程始终是实践性的：用户（user）在教员的指导下动手做某件事。

A tutorial is designed around an encounter that the learner can make sense of, in which the instructor is responsible for the learner’s safety and success.

教程围绕一场学习者能够理解的经历来设计，在这场经历中，教员对学习者的安全与成功负责。

A driving lesson is a good example of a tutorial.

驾驶课就是教程的一个好例子。

The purpose of the lesson is to develop skills and confidence in the student, not to get from A to B.

这堂课的目的是培养学生的技能和信心，而不是从 A 点开到 B 点。

A software example could be: Let’s create a simple game in Python.

软件领域的例子可以是：让我们用 Python 做一个简单的游戏。

The user will learn through what they do - not because someone has tried to teach them.

用户通过自己做的事来学会——而不是因为有人试图去教他们。

In documentation, the special difficulty is that the instructor is condemned to be absent, and is not there to monitor the learner and correct their mistakes.

在文档中，特殊的困难在于教员注定缺席，无法在场看护学习者、纠正他们的错误。

The instructor must somehow find a way to be present through written instruction alone.

教员必须设法仅凭书面指导实现“在场”。

A how-to guide addresses a real-world goal or problem, by providing practical directions to help the user who is in that situation.

操作指南面向真实世界中的目标或问题，通过提供实用的指引，帮助身处该情境中的用户。

A how-to guide always addresses an already-competent user, who is expected to be able to use the guide to help them get their work done.

操作指南面向的始终是已经具备能力的用户，我们预期他们能借助指南完成自己的工作。

In contrast to a tutorial, a how-to guide is concerned with work rather than study.

与教程相反，操作指南关心的是工作而非学习（study）。

A how-to guide might be: How to store cellulose nitrate film (in motion picture photography) or How to configure frame profiling (in software). Or even: Troubleshooting deployment problems.

操作指南可以是：如何存放硝酸纤维素胶片（电影摄影领域）或如何配置帧性能分析（软件领域）。甚至可以是：部署问题排查。

Reference guides contain the technical description - facts - that a user needs in order to do things correctly: accurate, complete, reliable information, free of distraction and interpretation.

参考指南包含技术性描述——事实——即用户把事情做对所需要的东西：准确、完整、可靠的信息，不夹杂干扰与解读。

They contain propositional or theoretical knowledge, not guides to action.

它们包含的是命题性知识或理论知识（theoretical knowledge），而不是行动（action）的指引。

Like a how-to guide, reference documentation serves the user who is at work, and it’s up to the user to be sufficiently competent to interpret and use it correctly.

和操作指南一样，参考文档服务于正在工作的用户，而用户自己要有足够的能力去正确地解读和使用它。

Reference material is neutral. It is not concerned with what the user is doing.

参考材料是中立的。它不关心用户正在做什么。

A marine chart could be used by a ship’s navigator to plot a course, but equally well by a prosecuting magistrate in a legal case.

一张海图可以被船上的领航员用来规划航线，也同样可以被检控官用在一桩法律案件里。

Where possible, the architecture of reference documentation should reflect the structure or architecture of the thing it’s describing - just like a map does.

在可能的情况下，参考文档的架构应当映照它所描述的事物的结构或架构——就像地图（map）那样。

If a method is part of a class that belongs to a certain module, then we should expect to see the same relationship in the documentation too.

如果一个方法属于某个类，而这个类又属于某个模块，那么我们应当期望在文档里也看到同样的关系。

Explanatory guides provide context and background.

阐释性的指南提供语境和背景。

They serve the need to understand and put things in a bigger picture.

它们服务于“理解事物并把事物放进更大图景”这一需求。

Explanation joins things together, and helps answer the question why?

阐释把事物连接起来，帮助回答那个为什么？

Explanation often needs to circle around its subject, and approach it from different directions.

阐释常常需要围绕主题盘旋，从不同方向去接近它。

It can contain opinions and take perspectives.

它可以包含观点，也可以采取立场视角。

Like reference, explanation belongs to the realm of propositional knowledge rather than action.

和参考一样，阐释属于命题性知识的领域，而非行动的领域。

However its purpose is to serve the user’s study - as tutorials do - and not their work.

然而它的目的是服务于用户的学习——正如教程那样——而不是他们的工作。

Often, writers of tutorials who are anxious that their students should know things overload their tutorials with distracting and unhelpful explanation.

写教程的人常常急于让学生知道各种东西，于是把教程塞满了让人分心、并无帮助的阐释。

It would be much more useful to give the learner the most minimal explanation (“Here, we use HTTPS because it’s safer”) and then link to an in-depth article (Secure communication using HTTPS encryption) for when the user is ready for it.

更有用的做法是只给学习者最精简的解释（“这里我们用 HTTPS，因为它更安全”），然后附上一篇深入文章的链接（使用 HTTPS 加密的安全通信），等用户准备好了再去读。

The four kinds of documentation and the relationships between them can be summarised in the Diátaxis map.

四种文档以及它们之间的关系，可以用 Diátaxis 地图来概括。

Diátaxis is not just a list of four different things, but a conceptual arrangement of them.

Diátaxis 不只是四样不同东西的清单，而是对它们的一种概念性编排。

It shows how the four kinds of documentation are related to each other, and distinct from each other.

它展示了四种文档彼此如何关联，又彼此如何区别。

Crossing or blurring the boundaries described in the map is at the heart of a vast number of problems in documentation.

越过或模糊地图上所描绘的边界，正是文档中大量问题的症结所在。

As you can see from the map:

从地图上可以看到：

On the other hand:

另一方面：

But a map doesn’t tell you what to do - it’s reference.

但地图不会告诉你该做什么——地图是参考。

To guide your action you need a different sort of tool, in this case, a kind of Diátaxis compass.

要指引你的行动，你需要另一种工具，在这里，就是一种 Diátaxis 罗盘（the compass）。

The compass is useful in two different ways.

罗盘在两种不同的情形下都很有用。

When creating documentation, it helps clarify your own intentions, and helps make sure you’re actually doing what you think you’re doing.

在创作文档时，它帮你厘清自己的意图，并帮你确认你实际在做的正是你以为自己在做的事。

When looking at documentation, it helps understand what’s going on in it, and makes problems stand out.

在审视文档时，它帮你理解文档里正在发生什么，并让问题凸显出来。

The compass is not nearly as eye-catching as the map, but when you’re at work puzzling over a documentation problem it’s what will help you move forward.

罗盘远不如地图抢眼，但当你在工作中为某个文档问题苦思冥想时，能帮你向前推进的正是它。

There is a very simple workflow for Diátaxis.

Diátaxis 有一个非常简单的工作流。

And then repeat.

然后重复。

That’s it.

就这么简单。

You can do what you like with Diátaxis.

你可以随自己的意来使用 Diátaxis。

You don’t have to believe in it and there is no exam. It is a wholly pragmatic approach.

你不必信奉它，也没有考试。它是一种彻底务实的方法。

I think it’s true, but what matters is that it actually helps people create better documentation.

我认为它是对的，但真正重要的是它确实能帮助人们创作出更好的文档。

If you find one idea or insight in it that seems to be worthwhile, help yourself to that.

如果你在其中发现了一个看起来有价值的想法或洞见，尽管拿去用。

There is an extensively elaborated theory around Diátaxis, but you don’t need to subscribe to it, or even read about it.

围绕 Diátaxis 有一套阐发得相当详尽的理论，但你不需要认同它，甚至不需要去读它。

Diátaxis doesn’t require a commitment to pursue it to a final end.

Diátaxis 并不要求你承诺把它贯彻到底。

You can do just one thing, right now, and even if you do nothing else ever after, you will at least have made that one improvement.

你可以现在就只做一件事，即便此后再不做别的，你也至少完成了那一处改进。

(In practice what you will find is that each thing you do will give you a clue as to the next thing to do - you only need to keep doing them.)

（实践中你会发现，你做的每一件事都会给你下一件事的线索——你只需要一直做下去。）

At this point, you have read everything you need to get started with Diátaxis.

到这里，上手 Diátaxis 所需要读的东西你已经全部读完了。

You can read more if you want, and eventually you probably should, but you will get the most value from the guidance in this website when you turn to it with a problem or a question. That’s when it comes alive.

想读更多当然可以，而且最终你大概也应该读，但当你带着一个问题或疑问来求助时，这个网站上的指引才会给你最大的价值。那一刻它才真正活起来。

The pages in this section are concerned with putting Diátaxis into practice.

本节各页关心的是：把 Diátaxis 付诸实践。

Diátaxis is underpinned by systematic theoretical principles, but understanding them is not necessary to make effective use of the system.

Diátaxis 底下有一套系统的理论原则作支撑，但要有效使用这套体系，并不需要先理解它们。

Diátaxis is primarily intended as a pragmatic approach for people working on documentation. Most of the key principles required to put it into practice successfully can be grasped intuitively.

Diátaxis 首先是为做文档的人准备的一套务实方法。成功实践所需的关键原则，大多凭直觉就能领会。

As soon as you feel you have picked up an idea that seems worth applying to your work, try applying it.

一旦你觉得抓到了一个值得用在自己工作上的想法，就去试着用。

Come back here when you need more clarity or reassurance. Iterate between your work and reflecting on your work.

需要更清晰的指引或想确认方向时再回到这里。在「做」与「对做的反思」之间来回迭代。

At the core of Diátaxis are the four different kinds of documentation it identifies. If you're encountering Diátaxis for the first time, start with these pages.

Diátaxis 的核心是它识别出的四种文档。若你初次接触 Diátaxis，请从这几页读起。

Diátaxis prescribes principles that guide action. These translate into particular ways of working, with implications for documentation process and execution.

Diátaxis 给出的是指导行动的原则。这些原则会落成具体的工作方式，进而影响文档的流程与执行。

Once you've made your first start, the tools and methods outlined here will help smooth your way.

迈出第一步之后，这里介绍的工具与方法会帮你把路走顺。

A tutorial is an experience that takes place under the guidance of a tutor.

教程（tutorial）是一种在导师指导下发生的体验。

A tutorial is always learning-oriented.

教程永远是以学习为导向的。

A tutorial is a practical activity, in which the student learns by doing something meaningful, towards some achievable goal.

教程是一种实践活动：学生通过做一件有意义的事、朝着某个可达成的目标前进，从中学到东西。

A tutorial serves the user’s acquisition of skills and knowledge - their study.

教程服务于用户（user）对技能和知识的习得（acquisition）——也就是他们的学习（study）。

Its purpose is not to help the user get something done, but to help them learn.

它的目的不是帮用户把某件事做完，而是帮他们学会。

A tutorial in other words is a lesson.

换句话说，教程就是一堂课。

It’s important to understand that while a student will learn by doing, what the student does is not necessarily what they learn.

有一点必须理解：虽然学生是在做中学，但学生做的东西并不一定就是他们学到的东西。

Through doing, they will acquire theoretical knowledge (i.e. facts), understanding, familiarity.

通过动手做，他们会习得理论知识（theoretical knowledge，即事实）、理解和熟悉感。

They will learn how things relate to each other and interact, and how to interact with them.

他们会学到事物之间如何关联、如何相互作用，以及自己如何与这些事物打交道。

They will learn the names of things, the use of tools, workflows, concepts, commands. And so on.

他们会学到事物的名称、工具的用法、工作流程、概念、命令，等等。

A lesson entails a relationship between a teacher and a pupil.

一堂课意味着教师与学生之间的一种关系。

In all learning of this kind, learning takes place as the pupil applies themself to tasks under the instructor’s guidance.

在所有这类学习中，学习发生在学生于指导者的引导下投入任务之时。

A lesson is a learning experience.

一堂课是一次学习体验。

In a learning experience, what matters is what the learner does and what happens.

在学习体验中，重要的是学习者做了什么、发生了什么。

By contrast, the teacher’s explanations and recitations of fact are far less important.

相比之下，教师的讲解和对事实的背诵远没有那么重要。

A good lesson gives the learner confidence, by showing them that they can be successful in a certain skill or with a certain product.

一堂好课会给学习者信心——让他们看到，自己可以在某项技能上、或在某个产品上获得成功。

A lesson is a kind of contract between teacher and student, in which nearly all the responsibility falls upon the teacher.

一堂课是教师与学生之间的一种契约，其中几乎所有的责任都落在教师身上。

The teacher has responsibility for what the pupil is to learn, what the pupil will do in order to learn it, and for the pupil’s success.

教师要对以下几件事负责：学生要学什么，学生为了学会它要做什么，以及学生能否成功。

Meanwhile, the only responsibility of the pupil in this contract is to be attentive and to follow the teacher’s directions as closely as they can.

与此同时，在这份契约中，学生唯一的责任就是保持专注，并尽可能严格地按照教师的指示去做。

There is no responsibility on the pupil to learn, understand or remember.

学生并不承担「学会、理解或记住」的责任。

At the same time, the exercise you put your pupils through must be:

与此同时，你让学生完成的练习必须是：

Tutorials are rarely done well, partly because they are genuinely difficult to do well, and partly because they are not well understood.

教程很少被做好，一部分原因是它确实很难做好，另一部分原因是人们对它理解不深。

In software, many products lack good tutorials, or lack tutorials completely; tutorials are often conflated with how-to guides.

在软件领域，许多产品缺少好的教程，或者根本没有教程；教程还常常与操作指南（how-to guide）混为一谈。

In an ideal lesson, the teacher is present and interacts with and responds to the student, correcting their mistakes and checking their learning.

在理想的课堂上，教师在场，与学生互动、回应学生，纠正他们的错误，检查他们的学习情况。

In documentation, none of this is possible.

在文档（documentation）里，这一切都做不到。

It’s hard enough to put together a learning experience that meets all the standards described above; in many contexts the product itself evolves rapidly, meaning that all that work needs to be done again to ensure that the tutorial still performs its required functions.

拼出一份满足上述全部标准的学习体验已经够难了；而在许多情境下，产品本身还在快速演进，这意味着所有这些工作都得重做一遍，才能确保教程仍然履行它应有的职能。

You will also often find that no other part of your documentation is subject to revisions the way your tutorials are.

你还会经常发现，文档的其他部分都不像教程这样需要频繁修订。

Elsewhere in documentation, changes and improvements can generally be made discretely; in tutorials, where the end-to-end learning journey must make sense, they often cascade through the entire story.

在文档的其他地方，修改和改进一般可以各自独立地进行；而在教程里，端到端的学习旅程必须说得通，因此改动往往会沿着整个故事层层连锁扩散。

Finally, tutorials contain the additional complication of the distinction between what is to be learned and what is to be done.

最后，教程还多了一层复杂性：要学的东西与要做的事情之间的区别。

Not only must the creator of a tutorial have a good sense of what the user must learn, and when, they must also devise a meaningful learning journey that somehow delivers all that.

教程的创作者不仅要清楚用户必须学什么、在何时学，还必须设计出一段有意义的学习旅程，把这一切设法交付出来。

A tutorial is a pedagogical problem.

教程是一个教学法问题。

It’s not an easy problem, but neither is it a mystery.

这个问题不容易，但也并非什么谜团。

The principles outlined below - repetition, action, small steps, results early and often, concreteness and so on - are not secrets, but they are not always well understood.

下面列出的原则——重复、行动（action）、小步前进、尽早且频繁地出结果、具体化等等——并不是什么秘密，但它们并不总是被充分理解。

Still, there are straightforward, effective ways to address the problems of pedagogy in practice.

尽管如此，在实践中应对教学法问题，还是有直截了当且有效的办法的。

The first rule of teaching is simply: don’t try to teach.

教学的第一条规则很简单：别试图去教。

Your job, as a teacher, is to provide the learner with an experience that will allow them to learn.

作为教师，你的工作是给学习者提供一段能让他们学到东西的体验。

A teacher inevitably feels a kind of anxiety to impart knowledge and understanding, but if you give into it and try to teach by telling and explaining, you will jeopardise the learning experience.

教师难免会有一种要传授知识和理解的焦虑，但如果你屈从于它，试图靠讲述和讲解来教学，你就会毁掉这段学习体验。

Instead, allow learning to take place, and trust that it will.

相反，要让学习自己发生，并且相信它会发生。

Give your learner things to do, through which they can learn.

给学习者一些可做的事，让他们借此学习。

Only your pupil can learn. Sadly, however much you desire it, you will not be able to learn for your pupil.

只有你的学生自己才能学。遗憾的是，无论你多么渴望，你都无法替学生去学。

You cannot make them learn. All you can do is make it so they can learn.

你没法让他们学会。你能做的，只是创造条件，让他们能够学会。

It’s important to allow the learner to form an idea of what they will achieve right from the start.

重要的是，让学习者从一开始就对自己将要达成什么形成概念。

As well as helping to set expectations, it allows them to see themselves building towards the completed goal as they work.

这不仅有助于设定预期，还能让他们在动手的过程中看到自己正一步步朝着完成的目标搭建。

Providing the picture the learner needs in a tutorial can be as simple as informing them at the outset: In this tutorial we will create and deploy a scalable web application. Along the way we will encounter containerisation tools and services.

在教程里给学习者提供他们需要的图景，可以简单到在开头告知一句：在本教程中，我们将创建并部署一个可扩展的 Web 应用。沿途我们会接触到容器化工具与服务。

This is not the same as saying: In this tutorial you will learn… - which is presumptuous and a very poor pattern.

这跟说「在本教程中你将学会……」不是一回事——后者自以为是，是一种非常糟糕的模式。

Your learner is probably doing new and strange things that they don’t fully understand.

你的学习者很可能正在做一些他们并不完全理解的、新奇陌生的事。

Understanding comes from being able to make connections between causes and effects, so let them see the results and make the connections rapidly and repeatedly.

理解来自于能够在因与果之间建立联系，所以要让他们快速地、反复地看到结果并建立起这些联系。

Each one of those results should be something that the user can see as meaningful.

其中每一个结果都应当是用户看得出有意义的东西。

Every step the learner follows should produce a comprehensible result, however small.

学习者跟着走的每一步，都应产生一个可理解的结果，哪怕再小也行。

At every step of a tutorial, the user experiences a moment of anxiety: will this action produce the correct result?

在教程的每一步，用户都会经历一个焦虑的瞬间：这个操作会产生正确的结果吗？

Part of the work of a successful tutorial is to keep providing feedback to the learner that they are indeed on the right path.

一份成功教程的部分工作，就是不断向学习者提供反馈，告诉他们确实走在正确的路上。

Keep up a narrative of expectations: “You will notice that …”; “After a few moments, the server responds with …”.

保持一条预期叙事：「你会注意到……」；「片刻之后，服务端会返回……」。

Show the user actual example output, or even the exact expected output.

给用户展示真实的示例输出，甚至是精确的预期输出。

If you know in advance what the likely signs of going wrong are, consider flagging them: “If the output doesn’t show …, you have probably forgotten to …”.

如果你事先知道出错时可能出现哪些迹象，可以考虑提前点出来：「如果输出里没有显示……，你多半是忘了……」。

It’s helpful to prepare the user for possibly surprising actions: “The command will probably return several hundred lines of logs in your terminal.”

让用户对可能令人吃惊的动作有心理准备也很有帮助：「这条命令很可能会在你的终端里返回几百行日志。」

Learning requires reflection.

学习需要反思。

This happens at multiple levels and depths, but one of the first is when the learner observes the signs in their environment.

反思发生在多个层次和深度上，但最初的一层，就是学习者观察到环境中的迹象。

In a lesson, a learner is typically too focused on what they are doing to notice them, unless they are prompted by the teacher.

在课堂上，学习者通常太专注于手头正在做的事，以至于注意不到这些迹象，除非教师加以提醒。

Your job as teacher is to close the loops of learning by pointing things out, in passing, as the lesson moves along.

作为教师，你的工作是在课程推进的过程中顺带把这些东西点出来，从而闭合学习的回路。

This can be as simple as pointing out how a command line prompt changes, for example.

这可以简单到比如指出命令行提示符发生了怎样的变化。

Observing is an active part of a craft, not a merely passive one.

观察是技艺（craft）中主动的一部分，而不只是被动的一部分。

It means paying attention to the environment, a skill in itself. It’s often neglected.

观察意味着留意环境，这本身就是一项技能。它常常被忽视。

In all skill or craft, the accomplished practitioner experiences a feeling of doing, a joined-up purpose, action, thinking and result.

在一切技能或技艺中，纯熟的实践者都会体验到一种做事的手感——目的、行动、思考与结果连成一气。

As skill develops, it flows in a confident rhythm and becomes a kind of pleasure.

随着技能的发展，它会流淌在一种自信的节奏里，并成为一种乐趣。

It’s the pleasure of walking, for example.

比如，这就像走路的乐趣。

Your learner’s skill depends upon their discovering this feeling, and its becoming a pleasure.

学习者的技能，取决于他们能否发现这种手感，以及这种手感能否变成一种乐趣。

Your challenge as the creator of a tutorial is to ensure that its tasks tie together purpose and action so they become a cradle for this feeling.

作为教程的创作者，你的挑战是确保教程中的任务把目的与行动系在一起，让它们成为孕育这种手感的摇篮。

Learners will return to and repeat an exercise that gives them success, for the pleasure they find in getting the expected result.

学习者会回头重做那些给了他们成功的练习，因为得到预期结果本身就让他们感到快乐。

Doing so reaffirms to them that they can do it, and that it works.

这样做向他们再次确认：自己做得到，而且这方法确实管用。

Repetition is a key to establishing the feeling of doing; being at home with that feeling is a foundational layer of learning.

重复是建立做事手感的关键；与这种手感相处自如，是学习的基础层。

In your tutorial, try to make it possible for a particular step and result to be repeated.

在你的教程里，要尽量让某个特定的步骤和结果可以被重复。

This can be difficult, for example in operations that are not reversible (making it hard to go back to a previous step) - but seek it wherever you can.

这可能不容易做到，比如遇上不可逆的操作（导致很难退回上一步）——但只要有可能，就要去争取。

Watching a user follow a tutorial, you may often be amazed to see how often they choose to repeat a step.

观察用户跟做教程时，你常常会惊讶于他们选择重复某一步的频率之高。

They are doing it just to see that the same thing really does happen again.

他们这么做，只是为了亲眼看到同样的事真的会再次发生。

A tutorial is not the place for explanation.

教程不是讲解的地方。

In a tutorial, the user is focused on correctly following your directions and getting the expected results.

在教程中，用户专注于正确地跟随你的指示、得到预期的结果。

Later, when they are ready, they will seek explanation, but right now they are concerned with doing.

之后，等他们准备好了，自然会去寻求讲解；但此刻，他们关心的是做。

Explanation distracts their attention from that, and blocks their learning.

讲解会把他们的注意力从「做」上引开，阻碍他们的学习。

For example, it’s quite enough to say something like: We’re using HTTPS because it’s more secure.

举个例子，说一句「我们使用 HTTPS，因为它更安全」就完全够了。

There is a place for extended discussion and explanation of HTTPS, but not now.

HTTPS 的展开讨论和讲解自有其归处，但不是现在。

Instead, provide a link or reference to that explanation, so that it’s available, but doesn’t get in the way.

取而代之，给那份讲解提供一个链接或引用，让它随时可取，又不碍事。

Explanation is one of the hardest temptations for a teacher to resist; even experienced teachers find it difficult to accept that their students’ learning does not depend on explanation.

讲解是教师最难抗拒的诱惑之一；即便是经验丰富的教师，也很难接受「学生的学习并不依赖讲解」这一点。

This is perfectly natural.

这完全是人之常情。

Once we have grasped something, we rely on the power of abstraction to frame it to ourselves - and that’s how we want to frame it to others.

一旦我们掌握了某样东西，就会依靠抽象的力量把它框定给自己——我们也想以同样的方式把它框定给别人。

Understanding means grasping general ideas, and abstraction is the logical form of understanding - but these are not what we need in a tutorial, and it’s not how successful learning or teaching works.

理解意味着把握一般性的观念，抽象是理解的逻辑形式——但这些并不是教程里需要的东西，成功的学习或教学也不是这样运作的。

One must see it for oneself, to see the focused attention of a student dissolve into air, when a teacher’s well-intentioned explanation breaks the magic spell of learning.

这得亲眼见过才能体会：当教师一番好意的讲解打破了学习的魔咒，学生凝聚的注意力便消散于无形。

In a learning situation, your student is in the moment, a moment composed of concrete things.

在学习情境中，你的学生处在当下——一个由具体事物构成的当下。

You are responsible for setting up and maintaining the student’s flow, from one concrete action and result to another.

你有责任建立并维持学生的心流，让它从一个具体的行动和结果流向下一个。

Focus on this problem, this action, this result, in such a way that you lead the learner from step to concrete step.

聚焦于这个问题、这个行动、这个结果，用这样的方式引导学习者从一个具体的步骤走向下一个具体的步骤。

It might seem that by maintaining focus on the concrete and particular that you deny the student the opportunity to see or grasp the larger general patterns, but the contrary is true.

看上去，始终聚焦于具体和特殊，似乎剥夺了学生看到或把握更大的一般性模式的机会——但事实恰恰相反。

The one thing our minds do spectacularly well is to perceive general patterns from concrete examples.

我们的头脑最擅长的一件事，就是从具体的例子中感知出一般性的模式。

All learning moves in one direction: from the concrete and particular, towards the general and abstract.

一切学习都朝着同一个方向前进：从具体和特殊，走向一般和抽象。

The latter will emerge from the former.

后者一定会从前者中浮现出来。

Your job is to guide the learner to a successful conclusion.

你的工作是引导学习者走到一个成功的终点。

There may be many interesting diversions along the way (different options for the command you’re using, different ways to use the API, different approaches to the task you’re describing) - ignore them.

沿途可能有许多有趣的岔路（你所用命令的不同选项、API 的不同用法、你所描述任务的不同做法）——统统忽略。

Your guidance needs to remain focused on what’s required to reach the conclusion, and everything else can be left for another time.

你的引导必须始终聚焦于抵达终点所必需的东西，其余一切都可以留到以后。

Doing this helps keep your tutorial shorter and crisper, and saves both you and the reader from having to do extra cognitive work.

这样做能让你的教程更短、更利落，也让你和读者都省去额外的认知（cognition）负担。

All of the above are general principles of pedagogy, but there is a special burden on the creator of a tutorial.

以上都是教学法的一般原则，但教程的创作者还背负着一份特殊的重担。

A tutorial must inspire confidence.

教程必须激发信心。

Confidence can only be built up layer by layer, and is easily shaken.

信心只能一层一层地累积起来，而且很容易被动摇。

At every stage, when you ask your student to do something, they must see the result you promise.

在每一个阶段，当你要求学生做某件事时，他们必须看到你承诺的那个结果。

A learner who follows your directions and doesn’t get the expected results will quickly lose confidence, in the tutorial, the tutor and themselves.

照着你的指示做却得不到预期结果的学习者，会迅速丧失信心——对教程、对导师、也对他们自己。

A teacher who’s there with the learner can rescue them when things go wrong.

陪在学习者身边的教师，可以在出问题时把他们救回来。

In a tutorial, you can’t do that.

在教程里，你做不到这一点。

Your tutorial ought to be so well constructed that things can’t go wrong, that your tutorial works for every user, every time.

你的教程应当构建得如此完善，以至于事情不可能出错——对每一位用户、每一次执行都行得通。

It’s hard work to create a reliable experience, but that is what you must aspire to in creating a tutorial.

创造一段可靠的体验是苦功夫，但这正是你在创作教程时必须追求的目标。

Your tutorial will have flaws and gaps, however carefully it is written.

无论写得多么用心，你的教程都会有缺陷和漏洞。

You won’t discover them all by yourself, you will have to rely on users to discover them for you.

你靠自己发现不了全部，你必须依靠用户替你发现它们。

The only way to learn what they are is by finding out what actually happens when users do the tutorial, through extensive testing and observation.

要弄清这些缺陷是什么，唯一的办法就是通过大量的测试和观察，弄明白用户做教程时实际发生了什么。

We …

我们……

The first-person plural affirms the relationship between tutor and learner: you are not alone; we are in this together.

第一人称复数确认了导师与学习者之间的关系：你不是一个人；我们在一起。

In this tutorial, we will …

在本教程中，我们将……

Describe what the learner will accomplish.

描述学习者将达成什么。

First, do x. Now, do y. Now that you have done y, do z.

首先，做 x。现在，做 y。既然你已经做完了 y，那就做 z。

No room for ambiguity or doubt.

不留任何含糊或疑虑的余地。

We must always do x before we do y because… (see Explanation for more details).

我们必须先做 x 再做 y，因为……（详见「阐释」部分）。

Provide minimal explanation of actions in the most basic language possible. Link to more detailed explanation.

用尽可能基础的语言，对行动给出最少量的讲解。链接到更详细的阐释（explanation）。

The output should look something like …

输出应该看起来大致像……

Give your learner clear expectations.

给学习者清晰的预期。

Notice that … Remember that … Let’s check …

注意…… 记住…… 我们来检查一下……

Give your learner plenty of clues to help confirm they are on the right track and orient themselves.

给学习者足够多的线索，帮助他们确认自己走在正确的轨道上，并辨明方向。

You have built a secure, three-layer hylomorphic stasis engine…

你已经建成了一台安全的三层质形停滞引擎……

Describe (and admire, in a mild way) what your learner has accomplished.

描述（并以温和的方式赞赏）学习者已经完成的成果。

Someone who has had the experience of teaching a child to cook will understand what matters in a tutorial, and just as importantly, the things that don’t matter at all.

教过孩子做饭的人会明白，教程里什么才重要——同样重要的是，明白哪些东西根本无关紧要。

It really doesn’t matter what the child makes, or how correctly they do it.

孩子做的是什么、做得多规范，真的无关紧要。

The value of a lesson lies in what the child gains, not what they produce.

一堂课的价值在于孩子收获了什么，而不是他们做出了什么。

Success in a cooking lesson with a child is not the culinary outcome, or whether the child can now repeat the processes on their own.

和孩子上一堂做饭课，成功与否不在于烹饪成果，也不在于孩子现在能否独自重复这些流程。

Success is when the child acquires the knowledge and skills you were hoping to impart.

成功在于孩子习得了你希望传授的知识和技能。

It’s a crucial condition of this that the child discovers pleasure in the experience of being in the kitchen with you, and wants to return to it.

而这一切有个关键条件：孩子要在「和你一起待在厨房里」这段体验中发现乐趣，并且想要再来。

Learning a skill is never a once and for all matter. Repetition is always required.

学一项技能从来不是一劳永逸的事。重复永远是必需的。

Meanwhile, the cooking lesson might be framed around the idea of learning how to prepare a particular dish, but what we actually need the child to learn might be things like: that we wash our hands before handling food; how to hold a knife; why the oil must be hot; what this utensil is called, how to time and measure things.

同时，这堂做饭课在名义上可能是围绕「学做某道菜」来设计的，但我们真正需要孩子学会的，也许是这样一些事：碰食物之前要先洗手；怎么握刀；油为什么必须烧热；这件厨具叫什么名字；怎么计时、怎么量取。

The child learns all this by working alongside you in the kitchen; in its own time, at its own pace, through the activities you do together, and not from the things you say or show.

孩子学会这一切，靠的是在厨房里和你并肩干活；按自己的时间、以自己的节奏，通过你们一起做的活动学会——而不是从你说的话或展示的东西里学会。

With a young child, you will often find that the lesson suddenly has to end before you’d completed what you set out to do.

对年幼的孩子，你会经常发现，课还没上到你原定的进度就不得不突然结束。

This is normal and expected; children have short attention spans.

这很正常，也在预料之中；孩子的注意力持续时间本来就短。

But as long as the child managed to achieve something - however small - and enjoyed doing it, it will have laid down something in the construction of its technical expertise, that can be returned to and built upon next time.

但只要孩子确实达成了点什么——再小也行——而且做得开心，就已经在其技术能力的构建中铺下了一块砖，下次可以回到这里、在此之上继续搭建。

How-to guides are directions that guide the reader through a problem or towards a result.

操作指南（how-to guide）是指引，引导读者穿越一个问题、走向一个结果。

How-to guides are goal-oriented.

操作指南是目标导向的。

A how-to guide helps the user get something done, correctly and safely; it guides the user’s action.

操作指南帮助用户（user）正确、安全地把事情做成；它引导的是用户的行动（action）。

It’s concerned with work - navigating from one side to the other of a real-world problem-field.

它关乎工作（work）——从一个现实世界问题域的这一端穿行到那一端。

Examples could be: how to calibrate the radar array; how to use fixtures in pytest; how to configure reconnection back-off policies.

例子可以是：如何校准雷达阵列；如何在 pytest 中使用 fixture；如何配置重连退避策略。

On the other hand, how to build a web application is not - that’s not addressing a specific goal or problem, it’s a vastly open-ended sphere of skill.

反过来，如何构建一个 Web 应用就不算——那并非针对某个具体的目标或问题，而是一片极其开放的技能领域。

How-to guides matter not just because users need to be able to accomplish things: the list of how-to guides in your documentation helps frame the picture of what your product can actually do.

操作指南之所以重要，不仅因为用户需要能把事情办成：你的文档（documentation）里操作指南的清单，还帮助勾勒出你的产品实际上能做什么的全貌。

A rich list of how-to guides is an encouraging suggestion of a product’s capabilities.

一份丰富的操作指南清单，是对产品能力的一种令人振奋的暗示。

Well-written how-to guides that address the right questions are likely to be the most-read sections of your documentation.

写得好、又切中正确问题的操作指南，很可能是你的文档中被阅读得最多的部分。

How-to guides must be written from the perspective of the user, not of the machinery.

操作指南必须站在用户的视角来写，而不是机器的视角。

A how-to guide represents something that someone needs to get done.

一份操作指南代表着某个人需要完成的某件事。

It’s defined in other words by the needs of a user.

换句话说，它由用户的需求（needs）来定义。

Every how-to guide should answer to a human project, in other words.

也就是说，每一份操作指南都应当回应一个属于人的任务计划。

It should show what the human needs to do, with the tools at hand, to obtain the result they need.

它应当展示：这个人需要做什么、用手头的工具怎么做，才能得到他们需要的结果。

This is in strong contrast to common pattern for how-to guides that often prevails, in which how-to guides are defined by operations that can be performed with a tool or system.

这与常见且往往盛行的操作指南套路形成强烈对比——在那种套路里，操作指南是由「某个工具或系统能执行的操作」来定义的。

The problem with this latter pattern is that it offers little value to the user; it is not addressed to any need the user has.

后一种套路的问题在于，它对用户几乎没有价值；它没有针对用户的任何需求。

Instead, it’s focused on the tool, on taking the machinery through its motions.

相反，它聚焦于工具本身，只是带着机器走一遍流程。

This is fundamentally a distinction of meaningfulness.

这从根本上说是一个关于意义的区分。

Meaning is given by purpose and need.

意义由目的和需求赋予。

There is no purpose or need in the functionality of a machine.

机器的功能里没有目的，也没有需求。

It is merely a series of causes and effects, inputs and outputs.

它不过是一连串的因与果、输入与输出。

Consider:

想想这两个例子：

We really do not need to be informed that we turn on a device using the power switch, but it is shocking how often how-to guides in software documentation are written at this level.

「用电源开关来开机」这种事实在无须告知，但令人震惊的是，软件文档里的操作指南竟有多少是写在这个水准上的。

The examples above look like examples of guidance, but they are not.

上面这些例子看起来像是在指引，但它们并不是。

They represent mostly useless information that anyone with basic competence - anyone who is working in this domain - should be expected to know.

它们呈现的信息大多毫无用处——任何具备基本能力的人、任何在这个领域里工作的人，都理应知道这些。

Between them, standardised interfaces and generally-expected knowledge should make it quite clear what effect most actions will have.

标准化的界面加上普遍应有的常识，两者合起来就足以让大多数操作会产生什么效果变得相当清楚。

Secondly, they are disconnected from purpose.

其次，它们与目的脱节。

What the user needs to know might be things like:

用户需要知道的可能是这样的事情：

How-to guides are about goals, projects and problems, not about tools.

操作指南关乎目标、任务计划和问题，而不关乎工具。

Tools appear in how-to guides as incidental bit-players, the means to the user’s end.

工具在操作指南里只是顺带出场的小配角，是通往用户目的的手段。

Sometimes of course, a particular end is closely aligned with a particular tool or part of the system, and then you will find that a how-to guide indeed concentrates on that.

当然，有时某个特定目的恰好与某个特定工具或系统的某一部分紧密对应，这时你会发现操作指南确实会集中在它上面。

Just as often, a how-to guide will cut across different tools or parts of a system, joining them up together in a series of activities defined by something a human being needs to get done.

但同样常见的是，操作指南会横跨不同的工具或系统的不同部分，把它们串联成一系列活动——这些活动由一个人需要完成的某件事来定义。

In either case, it is that project that defines what a how-to guide must cover.

无论哪种情况，决定操作指南必须涵盖什么的，都是那个任务计划本身。

How-to guides are wholly distinct from tutorials.

操作指南与教程（tutorial）截然不同。

They are often confused, but the user needs that they serve are quite different.

两者经常被混淆，但它们服务的用户需求相当不同。

Conflating them is at the root of many difficulties that afflict documentation.

把两者混为一谈，是困扰文档的许多难题的根源。

See The difference between a tutorial and how-to guide for a discussion of this distinction.

关于这一区分的讨论，参见《教程与操作指南的区别》。

In another confusion, how-to guides are often construed merely as procedural guides.

另一种混淆是，操作指南常常被单纯理解为按部就班的流程指引。

But solving a problem or accomplishing a task cannot always be reduced to a procedure.

但解决一个问题或完成一项任务，并不总能化约为一套固定流程。

Real-world problems do not always offer themselves up to linear solutions.

现实世界的问题并不总是乖乖交出线性的解法。

The sequences of action in a how-to guide sometimes need to fork and overlap, and they have multiple entry and exit-points.

操作指南里的行动序列有时需要分叉、需要交叠，而且有多个入口和出口。

Often, a how-to guide will need the user to rely on their judgement in applying the guidance it can provide.

很多时候，操作指南需要用户在运用它所提供的指引时，依靠自己的判断。

A how to-guide is concerned with work - a task or problem, with a practical goal. Maintain focus on that goal.

操作指南关乎工作——一项任务或一个问题，带着一个实践性的目标。始终聚焦于那个目标。

How-to characteristics

操作指南的特征

Anything else that’s added distracts both you and the user and dilutes the useful power of the guide.

任何额外添加的东西，都会同时分散你和用户的注意力，稀释指南的实用效力。

Typically, the temptations are to explain or to provide reference for completeness.

典型的诱惑是忍不住去阐释，或者为求完整而附上参考（reference）内容。

Neither of these are part of guiding the user in their work.

这两者都不属于「在工作中引导用户」的范畴。

They get in the way of the action; if they’re important, link to them.

它们会挡在行动的路上；如果它们确实重要，就放个链接指过去。

A how-to guide serves the work of the already-competent user, whom you can assume to know what they want to do, and to be able to follow your instructions correctly.

操作指南服务的是已具备能力的用户的工作，你可以假定他们知道自己想做什么，并且能正确地跟随你的指示。

A how-to guide needs to be adaptable to real-world use-cases.

操作指南需要能够适配现实世界的用例。

One that is useless for any purpose except exactly the narrow one you have addressed is rarely valuable.

一份除了你所针对的那个恰好狭窄的用途之外别无用处的指南，很少有价值。

You can’t address every possible case, so you must find ways to remain open to the range of possibilities, in such a way that the user can adapt your guidance to their needs.

你不可能覆盖每一种可能的情形，所以必须设法对各种可能性保持开放，让用户能把你的指引调适到他们自己的需求上。

In how-to guides, practical usability is more helpful than completeness.

在操作指南里，实用性比完整性更有帮助。

Whereas a tutorial needs to be a complete, end-to-end guide, a how-to guide does not.

教程需要是一份完整的、端到端的指引，而操作指南不必如此。

It should start and end in some reasonable, meaningful place, and require the reader to join it up to their own work.

它应当在某个合理而有意义的地方开始和结束，并要求读者自己把它衔接进自己的工作。

A how-to guide describes an executable solution to a real-world problem or task.

操作指南描述的是对一个现实问题或任务的可执行解法。

It’s in the form of a contract: if you’re facing this situation, then you can work your way through it by taking the steps outlined in this approach.

它的形式像一份契约：如果你正面临这种处境，那么按这套方法列出的步骤走，你就能闯过去。

The steps are in the form of actions.

这些步骤以行动的形式呈现。

“Actions” in this context includes physical acts, but also thinking and judgement - solving a problem involves thinking it through.

这里说的「行动」，既包括身体上的动作，也包括思考和判断——解决一个问题就包含把它想透。

A how-to guide should address how the user thinks as well as what the user does.

操作指南既要顾及用户做什么，也要顾及用户怎么想。

The fundamental structure of a how-to guide is a sequence.

操作指南的根本结构是一个序列。

It implies logical ordering in time, that there is a sense and meaning to this particular order.

这意味着时间上的逻辑排序——这个特定顺序自有其道理和意义。

In many cases, the ordering is simply imposed by the way things must be (step two requires completion of step one, for example).

很多情况下，顺序干脆就是被事物的必然规律强加的（比如第二步要求先完成第一步）。

In this case it’s obvious what order your directions should take.

这种情况下，你的指引该按什么顺序写是一目了然的。

Sometimes the need is more subtle - it might be possible to perform two operations in either order, but if for example one operation helps set up the user’s working environment or even their thinking in a way that benefits the other, that’s a good reason for putting it first.

有时候这种需要更微妙——两项操作也许先执行哪个都行，但如果其中一项能帮用户搭好工作环境、甚至理顺思路，从而让另一项受益，那就是把它放在前面的好理由。

At all times, try to ground your sequences in the patterns of the user’s activities and thinking, in such a way that the guide acquires flow: smooth progress.

要始终设法让你的序列扎根于用户活动与思考的模式之中，让指南获得心流（flow）：顺畅的推进。

Achieving flow means successfully understanding the user.

达成心流意味着成功地理解了用户。

Paying attention to sense and meaning in ordering requires paying attention to the way human beings think and act, and the needs of someone following directions.

关注排序的道理与意义，就要求关注人类思考和行动的方式，以及一个跟着指引走的人的需求。

Again, this can be somewhat obvious: a workflow that has the user repeatedly switching between contexts and tools is clearly clumsy and inefficient.

同样，这有时相当明显：一个让用户反复在不同上下文和工具之间切换的工作流，显然又笨拙又低效。

But you should look more deeply than this.

但你应当看得比这更深。

What are you asking the user to think about, and how will their thinking flow from subject to subject during their work?

你在要求用户思考什么？在工作过程中，他们的思绪会怎样从一个主题流向另一个主题？

How long do you require the user to hold thoughts open before they can be resolved in action?

你要求用户把一些念头悬着多久，才能在行动中把它们了结？

If you require the user to jump back to earlier concerns, is this necessary or avoidable?

如果你要求用户跳回先前的事项，这是必要的，还是可以避免的？

A how-to guide is concerned not just with logical ordering in time, but action taking place in time.

操作指南关心的不只是时间上的逻辑排序，还有在时间中展开的行动本身。

Action, and a guide to it, has pace and rhythm.

行动，以及对行动的指引，是有步调和节奏的。

Badly-judged pace or disrupted rhythm are both damaging to flow.

步调拿捏失当或节奏被打断，都会破坏心流。

At its best, how-to documentation gives the user flow.

操作类文档做到极致时，会带给用户心流。

There is a distinct experience of encountering a guide that appears to anticipate the user - the documentation equivalent of a helper who has the tool you were about to reach for, ready to place it in your hand.

遇到一份仿佛能预判用户的指南，是一种独特的体验——相当于文档界的一位帮手：你正要伸手去拿的工具，他已经拿在手里，准备递到你手上。

Choose titles that say exactly what a how-to guide shows.

选择能准确说出这份操作指南展示了什么的标题。

Note that search engines appreciate good titles just as much as humans do.

注意，搜索引擎和人类一样欣赏好标题。

This guide shows you how to…

本指南向你展示如何……

Describe clearly the problem or task that the guide shows the user how to solve.

清楚地描述这份指南要向用户展示如何解决的问题或任务。

If you want x, do y. To achieve w, do z.

如果你想要 x，就做 y。要达成 w，就做 z。

Use conditional imperatives.

使用条件式祈使句。

Refer to the x reference guide for a full list of options.

完整的选项列表请查阅 x 参考指南。

Don’t pollute your practical how-to guide with every possible thing the user might do related to x.

不要把用户围绕 x 可能做的每一件事都塞进来，污染你这份实用的操作指南。

Consider a recipe, an excellent model for a how-to guide.

想想菜谱吧，它是操作指南的一个绝佳范本。

A recipe clearly defines what will be achieved by following it, and addresses a specific question (How do I make…? or What can I make with…?).

菜谱清楚地定义了照着做会达成什么，并且针对一个具体的问题（我怎么做……？或者用……我能做什么？）。

It’s not the responsibility of a recipe to teach you how to make something.

教你怎么做出一道菜，并不是菜谱的责任。

A professional chef who has made exactly the same thing multiple times before may still follow a recipe - even if they created the recipe themselves - to ensure that they do it correctly.

一位已经把同一道菜做过许多次的职业厨师，仍然可能照着菜谱做——哪怕这份菜谱就是他自己创制的——以确保自己做得无误。

Even following a recipe requires at least basic competence.

即便只是照菜谱做菜，也至少需要基本的能力。

Someone who has never cooked before should not be expected to follow a recipe with success, so a recipe is not a substitute for a cooking lesson.

不应指望一个从没下过厨的人能照着菜谱做成功，所以菜谱替代不了烹饪课。

Someone who expected to be provided with a recipe, and is given instead a cooking lesson, will be disappointed and annoyed.

一个人期待拿到的是菜谱，结果被塞了一堂烹饪课，他会又失望又恼火。

Similarly, while it’s interesting to read about the context or history of a particular dish, the one time you don’t want to be faced with that is while you are in the middle of trying to make it.

同样，读一读某道菜的背景或历史固然有趣，但你唯独不想撞见这些内容的时刻，就是你正做这道菜做到一半的时候。

A good recipe follows a well-established format, that excludes both teaching and discussion, and focuses only on how to make the dish concerned.

一份好菜谱遵循一套约定俗成的格式：既不教学也不讨论，只聚焦于如何做出这道菜。

Reference guides are technical descriptions of the machinery and how to operate it.

参考（reference）指南是对机器装置及其操作方法的技术描述。

Reference material is information-oriented.

参考材料是信息导向的。

Reference material contains propositional or theoretical knowledge that a user looks to in their work.

参考材料包含命题性或理论性的知识，是用户（user）在工作（work）中要查阅的东西。

The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way.

参考指南的唯一目的就是描述——尽可能简洁，并且井然有序。

Whereas the content of tutorials and how-to guides are led by needs of the user, reference material is led by the product it describes.

教程（tutorial）和操作指南（how-to guide）的内容由用户的需求（needs）主导，而参考材料则由它所描述的产品主导。

In the case of software, reference guides describe the software itself - APIs, classes, functions and so on - and how to use them.

就软件而言，参考指南描述软件本身——API、类、函数等等——以及如何使用它们。

Your users need reference material because they need truth and certainty - firm platforms on which to stand while they work.

你的用户需要参考材料，因为他们需要真实与确定——供他们工作时立足的坚实平台。

Good technical reference is essential to provide users with the confidence to do their work.

好的技术参考必不可少，它为用户提供开展工作的信心。

Reference material describes the machinery. It should be austere.

参考材料描述机器装置。它应当是朴素克制的。

One hardly reads reference material; one consults it.

人们很少通读参考材料；人们查阅它。

There should be no doubt or ambiguity in reference; it should be wholly authoritative.

参考中不应有疑问或含糊；它应当是完全权威的。

Reference material is like a map.

参考材料就像一张地图（map）。

A map tells you what you need to know about the territory, without having to go out and check the territory for yourself; a reference guide serves the same purpose for the product and its internal machinery.

地图告诉你需要了解的关于这片地域的信息，而无需你亲自出门去核查这片地域；参考指南对产品及其内部机器装置起着同样的作用。

Although reference should not attempt to show how to perform tasks, it can and often needs to include a description of how something works or the correct way to use it.

虽然参考不应试图展示如何执行任务，但它可以、也常常需要包含对某样东西如何运作或其正确用法的描述。

Some reference material (such as API documentation) can be generated automatically by the software it describes, which is a powerful way of ensuring that it remains faithfully accurate to the code.

某些参考材料（比如 API 文档）可以由它所描述的软件自动生成，这是确保参考材料对代码保持忠实准确的一种有力方式。

Neutral description is the key imperative of technical reference.

中立的描述是技术参考的首要准则。

Style and form

风格与形式

Unfortunately one of the hardest things to do is to describe something neutrally.

遗憾的是，最难做到的事情之一就是中立地描述某样东西。

It’s not a natural way of communicating.

这不是一种自然的交流方式。

What’s natural on the other hand is to explain, instruct, discuss, opine, and all these things run counter to the needs of technical reference, which instead demands accuracy, precision, completeness and clarity.

反之，自然而然的做法是去阐释、指导、讨论、发表见解，而这些都与技术参考的需求背道而驰——技术参考要求的是准确、精确、完整与清晰。

It can be tempting to introduce instruction and explanation, simply because description can seem too inadequate to be useful, and because we do indeed need these other things.

人们很容易忍不住引入指导和阐释（explanation），只因为描述看上去太单薄、不够有用，也因为我们确实需要那些别的东西。

Instead, link to how-to guides, explanation and introductory tutorials.

正确的做法是：链接到操作指南、阐释和入门教程。

Reference material is useful when it is consistent.

参考材料在保持一致时才有用。

Standard patterns are what allow us to use reference material effectively.

标准模式正是让我们能够有效使用参考材料的东西。

Your job is to place the material that your user needs where they expect to find it, in a format that they are familiar with.

你的职责是把用户需要的材料放在他们预期能找到的位置，并用他们熟悉的格式呈现。

There are many opportunities in writing to delight your readers with your extensive vocabulary and command of multiple styles, but reference material is definitely not one of them.

写作中有许多机会可以用你丰富的词汇和驾驭多种文体的功力来取悦读者，但参考材料绝对不是其中之一。

The way a map corresponds to the territory it represents helps us use the former to find our way through the latter.

地图与它所代表的地域之间的对应关系，帮助我们借助前者在后者之中找到方向。

It should be the same with documentation: the structure of the documentation should mirror the structure of the product, so that the user can work their way through them at the same time.

文档也应如此：文档的结构应当映照产品的结构，让用户可以同步地在两者之间穿行。

It doesn’t mean forcing the documentation into an unnatural structure.

这并不意味着把文档硬塞进一个不自然的结构里。

What’s important is that the logical, conceptual arrangement of and relations within the code should help make sense of the documentation.

重要的是，代码内部在逻辑和概念上的编排与关系，应当有助于理解文档。

Examples are valuable ways of providing illustration that helps readers understand reference, while avoiding the risk of becoming distracted from the job of describing.

示例是很有价值的说明手段，既能帮助读者理解参考，又能避免偏离描述这一本职工作的风险。

For example, an example of usage of a command can be a succinct way of illustrating it and its context, without falling into the trap of trying to explain or instruct.

比如，一条命令的用法示例可以简洁地展示这条命令及其上下文，而不落入试图阐释或指导的陷阱。

State facts about the machinery and its behaviour.

陈述关于机器装置及其行为的事实。

List commands, options, operations, features, flags, limitations, error messages, etc.

列出命令、选项、操作、特性、标志、限制、错误信息等等。

Provide warnings where appropriate.

在适当之处给出警告。

You might check the information on a packet of food, in order to help you make a decision about what to do.

你可能会查看一包食品上的信息，来帮助自己决定接下来做什么。

When you’re looking for information - relevant facts - you do not want to be confronted by opinions, speculation, instructions or interpretation.

当你在寻找信息——相关的事实——的时候，你不想迎面撞上观点、猜测、指令或解读。

You also expect that information to be presented in standard ways, so that you - when you need to know about something’s nutritional properties, how it should be stored, its ingredients, what health implications it might have - can find them quickly, and know you can rely on them.

你还期望这些信息以标准的方式呈现，这样当你需要了解某样东西的营养成分、应当如何储存、配料是什么、可能有什么健康影响时，都能迅速找到，并且知道自己可以信赖它们。

So you expect to see for example: May contain traces of wheat. Or: Net weight: 1000g.

所以你期望看到的是诸如：可能含有微量小麦。或者：净含量：1000 克。

You will certainly not expect to find for example recipes or marketing claims mixed up with this information; that could be literally dangerous.

你绝不会期望看到比如食谱或营销宣传混杂在这些信息之中；那可能是名副其实的危险。

The way reference material is presented on food products is so important that it’s usually governed by law, and the same kind of seriousness should apply to all reference documentation.

参考材料在食品上的呈现方式是如此重要，以至于通常由法律来规范；同样的严肃态度也应当适用于所有参考文档。

Explanation is a discursive treatment of a subject, that permits reflection.

阐释（explanation）是对一个主题的论述式处理，它允许反思（reflection）。

Explanation is understanding-oriented.

阐释以理解为导向。

Explanation deepens and broadens the reader’s understanding of a subject.

阐释加深并拓宽读者对一个主题的理解。

It brings clarity, light and context.

它带来清晰、光亮与语境。

The concept of reflection is important.

反思这个概念很重要。

Reflection occurs after something else, and depends on something else, yet at the same time brings something new - shines a new light - on the subject matter.

反思发生在其他事情之后，也依赖于其他事情，但同时又为所论的主题带来新的东西——照进一道新的光。

The perspective of explanation is higher and wider than that of the other three types.

阐释的视角比其他三种类型更高、更宽。

It does not take the user’s eye-level view, as in a how-to guide, or a close-up view of the machinery, like reference material.

它不像操作指南（how-to guide）那样采取用户（user）的平视视角，也不像参考（reference）材料那样对机器做特写式的贴近观察。

Its scope in each case is a topic - “an area of knowledge”, that somehow has to be bounded in a reasonable, meaningful way.

它每一次的范围都是一个话题——「一个知识领域」，这个领域总得以某种合理而有意义的方式划定边界。

For the user, explanation joins things together.

对用户来说，阐释把事物连结在一起。

It’s an answer to the question: Can you tell me about …?

它回答的是这样的问题：你能给我讲讲……吗？

It’s documentation that it makes sense to read while away from the product itself (one could say, explanation is the only kind of documentation that it might make sense to read in the bath).

这是那种离开产品本身去读也说得通的文档（documentation）（可以说，阐释是唯一一种连在浴缸里读也许都说得通的文档）。

Explanation is characterised by its distance from the active concerns of the practitioner.

阐释的特征在于它与实践者当下关切之间的距离。

It doesn’t have direct implications for what they do, or for their work.

它对实践者做的事、对他们的工作，都没有直接的影响。

This means that it’s sometimes seen as being of lesser importance.

这意味着它有时被看作不那么重要。

That’s a mistake; it may be less urgent than the other three, but it’s no less important. It’s not a luxury.

这是个错误；它也许不如其他三种紧迫，但绝不比它们次要。它不是奢侈品。

No practitioner of a craft can afford to be without an understanding of that craft, and needs the explanatory material that will help weave it together.

任何一门技艺（craft）的实践者都承受不起对这门技艺缺乏理解的代价，都需要那些帮助把理解编织起来的阐释性材料。

Your explanation documentation doesn’t need to be called Explanation.

你的阐释文档不一定非得叫「阐释」。

Alternatives include:

备选名称包括：

The word explanation - and its cognates in other languages - refer to unfolding, the revelation of what is hidden in the folds.

explanation 这个词——以及它在其他语言中的同源词——指的是展开（unfolding），把折叠中隐藏的东西揭示出来。

So explanation brings to the light things that were implicit or obscured.

所以阐释把原本隐含或被遮蔽的东西带到光亮之下。

Similarly, words that mean understanding share roots in words meaning to hold or grasp (as in comprehend).

类似地，表示理解的词与表示握住或抓住的词同根（比如 comprehend，领会）。

That’s an important part of understanding, to be able to hold something or be in possession of it.

这正是理解的重要部分：能够把某样东西握在手里，或者说据为己有。

Understanding seals together the other components of our mastery of a craft, and makes it safely our own.

理解把我们对一门技艺的掌握中的其他成分封合在一起，使这门技艺稳稳地成为我们自己的东西。

Understanding doesn’t come from explanation, but explanation is required to form that web that helps hold everything together.

理解并不来自阐释，但要织成那张把一切维系在一起的网，阐释必不可少。

Without it, the practitioner’s knowledge of their craft is loose and fragmented and fragile, and their exercise of it is anxious.

没有它，实践者对自己技艺的知识就是松散、破碎而脆弱的，施展起来也惶惶不安。

Quite often explanation is not explicitly recognised in documentation; and the idea that things need to be explained is often only faintly expressed.

很多时候，阐释在文档中并没有被明确承认；「事情需要被解释」这个想法也往往只被隐约地表达出来。

Instead, explanation tends to be scattered in small parcels in other sections.

相反，阐释往往被拆成小包，零零散散地落在其他章节里。

It’s not always easy to write good explanatory material.

写出好的阐释性材料并不总是容易。

Where does one start? It’s also not clear where to conclude.

从哪里开始？在哪里收尾也不清楚。

There is an open-endedness about it that can give the writer too many possibilities.

它有一种开放无边的性质，会给写作者太多的可能性。

Tutorials, how-to-guides and reference are all clearly defined in their scope by something that is also well-defined: by what you need the user to learn, what task the user needs to achieve, or just by the scope of the machine itself.

教程（tutorial）、操作指南和参考的范围，都由某个同样清晰明确的东西界定：你需要用户学会什么、用户需要完成什么任务，或者干脆就是机器本身的范围。

In the case of explanation, it’s useful to have a real or imagined why question to serve as a prompt.

就阐释而言，拿一个真实的或想象出来的「为什么」问题当作引子会很有用。

Otherwise, you simply have to draw some lines that mark out a reasonable area and be satisfied with that.

否则，你只能划出几条线，圈出一片合理的区域，并对此感到满足。

When writing explanation you are helping to weave a web of understanding for your readers.

写阐释时，你是在帮读者编织一张理解之网。

Make connections to other things, even to things outside the immediate topic, if that helps.

与其他事物建立连结——如果有帮助，甚至可以连到眼前话题之外的东西。

Provide background and context in your explanation: explain why things are so - design decisions, historical reasons, technical constraints - draw implications, mention specific examples.

在阐释中提供背景与语境：解释事情为什么是这样——设计决策、历史原因、技术约束——引出推论，举出具体例子。

Explanation guides are about a topic in the sense that they are around it.

阐释指南是「关于」（about）一个话题的，意思是它们「围绕」（around）着这个话题。

Even the names of your explanation guides should reflect this; you should be able to place an implicit (or even explicit) about in front of each title.

就连阐释指南的标题也应该体现这一点；你应该能在每个标题前面加上一个隐含的（甚至明写出来的）「关于」。

For example: About user authentication, or About database connection policies.

例如：《关于用户身份认证》，或《关于数据库连接策略》。

Opinion might seem like a funny thing to introduce into documentation.

把观点引入文档，看起来可能有点奇怪。

The fact is that all human activity and knowledge is invested within opinion, with beliefs and thoughts.

事实是，人类的一切活动和知识都浸润在观点之中，带着信念与想法。

The reality of any human creation is rich with opinion, and that needs to be part of any understanding of it.

任何人类创造物的真实面貌都富含观点，而这必须成为对它的任何理解的一部分。

Similarly, any understanding comes from a perspective, a particular stand-point - which means that other perspectives and stand-points exist.

类似地，任何理解都出自某个视角、某个特定的立足点——这就意味着还存在其他的视角和立足点。

Explanation can and must consider alternatives, counter-examples or multiple different approaches to the same question.

阐释可以而且必须考虑替代方案、反例，或者对同一问题的多种不同思路。

In explanation, you’re not giving instruction or describing facts - you’re opening up the topic for consideration.

在阐释中，你不是在下指令，也不是在描述事实——你是在把话题打开，供人考量。

It helps to think of explanation as discussion: discussions can even consider and weigh up contrary opinions.

把阐释想成讨论会有帮助：讨论甚至可以考虑并权衡相互对立的观点。

One risk of explanation is that it tends to absorb other things.

阐释的一个风险是，它容易吸纳其他东西。

The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it.

写作者一心想把话题讲全，会忍不住把相关的指令或技术描述也塞进来。

But documentation already has other places for these, and allowing them to creep in interferes with the explanation itself, and removes them from view in the correct place.

但文档里已经有别的地方安放这些内容；任由它们混进来，既干扰阐释本身，也让它们从本该出现的正确位置上消失。

The reason for x is because historically, y …

「x 之所以如此，是因为历史上 y……」

Explain.

解释。

W is better than z, because …

「w 比 z 好，因为……」

Offer judgements and even opinions where appropriate..

在合适的地方给出判断，甚至观点。

An x in system y is analogous to a w in system z. However …

「系统 y 中的 x 类似于系统 z 中的 w。不过……」

Provide context that helps the reader.

提供能帮助读者的语境。

Some users prefer w (because z). This can be a good approach, but…

「有些用户偏爱 w（因为 z）。这可以是个好办法，但……」

Weigh up alternatives.

权衡各种替代方案。

An x interacts with a y as follows: …

「x 与 y 的交互方式如下：……」

Unfold the machinery’s internal secrets, to help understand why something does what it does.

展开机器内部的秘密，帮助读者理解某样东西为什么会有这样的行为。

In 1984 Harold McGee published On food and cooking.

1984 年，哈罗德·麦基（Harold McGee）出版了《食物与烹饪》（On food and cooking）。

The book doesn’t teach how to cook anything.

这本书不教你烹制任何东西。

It doesn’t contain recipes (except as historical examples) and it isn’t a work of reference.

它不收菜谱（除非作为历史例证），也不是一部参考著作。

Instead, it places food and cooking in the context of history, society, science and technology.

相反，它把食物与烹饪放进历史、社会、科学与技术的语境之中。

It explains for example why we do what we do in the kitchen and how that has changed.

比如，它解释我们在厨房里为什么这样做，以及这些做法是如何演变的。

It’s clearly not a book we would read while cooking.

显然，这不是一本我们会边做饭边读的书。

We would read when we want to reflect on cooking.

我们会在想对烹饪进行反思的时候去读它。

It illuminates the subject by taking multiple different perspectives on it, shining light from different angles.

它从多个不同的视角来观照这个主题，从不同的角度打光，把它照亮。

After reading a book like On food and cooking, our understanding is changed.

读完《食物与烹饪》这样一本书，我们的理解就变了。

Our knowledge is richer and deeper.

我们的知识更丰富、更深厚了。

What we have learned may or may not be immediately applicable next time we are doing something in the kitchen, but it will change how we think about our craft, and will affect our practice.

我们学到的东西，下次在厨房做事时未必立刻用得上，但它会改变我们对自己这门技艺的思考方式，并将影响我们的实践。

The Diátaxis map is an effective reminder of the different kinds of documentation and their relationship, and it accords well with intuitions about documentation.

Diátaxis 地图（map）能有效提醒我们文档（documentation）有哪些不同种类以及它们之间的关系，而且它与人们对文档的直觉相当吻合。

However intuition is not always to be relied upon. Often when working with documentation, an author is faced with the question: what form of documentation is this? or what form of documentation is needed here? - and no obvious, intuitive answer.

然而直觉并不总是靠得住。做文档工作时，作者常常面临这样的问题：这是哪种形式的文档？或者这里需要哪种形式的文档？——却没有显而易见的直觉答案。

Worse, sometimes intuition provides an immediate answer that is also wrong.

更糟的是，有时直觉会立刻给出一个答案，但这个答案是错的。

A map is most powerful in unfamiliar territory when we also have a compass to guide us.

在陌生的地域里，地图只有配上一只指引方向的罗盘（compass），才能发挥最大的威力。

The Diátaxis compass is something like a truth-table or decision-tree of documentation. It reduces a more complex, two-dimensional problem to its simpler parts, and provides the author with a course-correction tool.

Diátaxis 罗盘有点像文档的真值表或决策树。它把一个较复杂的二维问题化简为更简单的部分，为作者提供了一个纠偏工具。

The compass can be applied equally to user situations that need documentation, or to documentation itself that perhaps needs to be moved or improved. Like many good tools, it’s surprisingly banal.

罗盘既可以用于需要文档的用户情境，也同样可以用于文档本身——它也许需要挪动位置或加以改进。和许多好工具一样，它平淡无奇得出人意料。

To use the compass, just two questions need to be asked: action or cognition? acquisition or application?

使用罗盘只需要问两个问题：行动（action）还是认知（cognition）？习得（acquisition）还是应用（application）？

And it yields the answer.

它就会给出答案。

The compass is particularly effective when you think that you (or even the documentation in front of you) are doing one thing - but you are troubled by a sense of doubt, or by some difficulty in the work. The compass forces you to stop and reconsider.

当你以为自己（甚至你面前的文档）在做某件事，却被一种疑虑或工作中的某种困难所困扰时，罗盘尤其有效。罗盘迫使你停下来重新思考。

Especially when you are trying to find your initial bearings, use the compass’s terms flexibly; don’t get fixated on the exact names.

尤其在你还在寻找最初方位的时候，要灵活地使用罗盘上的这些词；别死抠字面上的名称。

And the questions themselves can also be used in different ways:

而这两个问题本身也可以用不同的方式来问：

And try applying them close-up, at the level of sentences and words, or from a wider perspective, considering an entire document.

还可以试着在近距离——句子和词语的层面——运用它们，或者从更宽的视角出发，审视整篇文档。

As well as providing a guide to documentation content, Diátaxis is also a guide to documentation process and execution.

Diátaxis 不仅是文档（documentation）内容的指南，也是文档流程与执行的指南。

Most people who work on technical documentation must make decisions about how to work, as they work.

大多数从事技术文档工作的人，都必须在工作的同时决定如何工作。

In some contexts, documentation must be delivered once, complete and in its final state, but it’s more usual that it’s an on-going project, for example developed alongside a product that itself evolves and develops.

在某些情境下，文档必须一次性交付，完整并处于最终状态；但更常见的情况是，它是一个持续进行的项目，例如与一个本身也在演进发展的产品同步开发。

It’s also the experience of many people who work on documentation to find themselves responsible for improving or even remediating a body of work.

许多文档工作者也有这样的经历：发现自己要负责改进、甚至修复一整套既有的文档。

Diátaxis provides an approach to work that runs counter to much of the accepted wisdom in documentation.

Diátaxis 提供的工作方式，与文档领域许多公认的常识背道而驰。

In particular, it discourages planning and top-down workflows, preferring instead small, responsive iterations from which overall patterns emerge.

尤其是，它不鼓励做计划和自上而下的工作流，而是偏好小步、响应式的迭代，让整体模式从中自然浮现。

Diátaxis describes a complete picture of documentation.

Diátaxis 描绘了文档的一幅完整图景。

However the structure it proposes is not intended to be a plan, something you must complete in your documentation.

然而它提出的结构并不是要当作一份计划——不是你必须在文档里逐项完成的东西。

It’s a guide, a map to help you check that you’re in the right place and going in the right directions.

它是一份指南，一张地图（map），帮你确认自己是否身处正确的位置、朝着正确的方向前进。

The point of Diátaxis is to give you a way to think about and understand your documentation, so that you can make better sense of what it’s doing and what you’re trying to do with it.

Diátaxis 的意义在于给你一种思考和理解自己文档的方式，让你更清楚它在做什么、你想用它做什么。

It provides tools that help assess it, identify where its problems lie, and judge what you can do to improve it.

它提供的工具能帮你评估文档、找出问题所在，并判断你能做些什么来改进它。

Although structure is key to documentation, using Diátaxis means not spending energy trying to get its structure correct.

虽然结构对文档至关重要，但使用 Diátaxis 意味着不必花力气去把结构弄“正确”。

If you continue to follow the prompts that Diátaxis provides, eventually your documentation will assume the Diátaxis structure - but it will have assumed that shape because it has been improved.

只要你持续跟随 Diátaxis 给出的提示，你的文档最终会呈现出 Diátaxis 的结构——但它之所以长成那个形状，是因为它被改进了。

It’s not the other way round, that the structure must be imposed upon documentation to improve it.

而不是反过来——必须先把结构强加给文档，才能改进它。

Getting started with Diátaxis does not require you to think about dividing up your documentation into four sections.

开始使用 Diátaxis，并不需要你考虑把文档划分成四个部分。

It certainly does not mean that you should create empty structures for tutorials/howto guides/reference/explanation with nothing in them.

它更绝不意味着你应该为教程（tutorial）/操作指南（how-to guide）/参考（reference）/阐释（explanation）建好空架子，里面什么都没有。

Don’t do that. It’s horrible.

别那么做。那很糟糕。

Instead, following the workflow described in the next two sections, make changes where you see opportunities for improvement according to Diátaxis principles, so that the documentation starts to take a certain shape.

相反，按照接下来两节描述的工作流，在你依据 Diátaxis 原则看到改进机会的地方做出修改，让文档开始呈现出某种形状。

At a certain point, the changes you have made will appear to demand that you move material under a certain Diátaxis heading - and that is how your top-level structure will form.

到了某个时刻，你所做的修改会仿佛自己提出要求：该把某些材料挪到某个 Diátaxis 标题之下了——你的顶层结构就是这样形成的。

In other words, Diátaxis changes the structure of your documentation from the inside.

换句话说，Diátaxis 是从内部改变你文档的结构。

Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.

Diátaxis 强力地规定了一种结构，但无论你现有文档处于什么状态——哪怕按任何标准衡量都是一团糟——都总有可能迭代地改进它。

It’s natural to want to complete large tranches of work before you publish them, so that you have something substantial to show each time.

人们自然想先完成一大块工作再发布，好让每次都拿得出实质性的成果。

Avoid this temptation - every step in the right direction is worth publishing immediately.

要抵住这种诱惑——朝正确方向迈出的每一步，都值得立即发布。

Although Diátaxis is intended to provide a big picture of documentation, don’t try to work on the big picture. It’s both unnecessary and unhelpful.

虽然 Diátaxis 旨在提供文档的全局图景，但别试图在全局图景上开工。那既没必要，也没帮助。

Diátaxis is designed to guide small steps; keep taking small steps to arrive where you want to go.

Diátaxis 就是为引导小步前进而设计的；不断迈出小步，就能抵达你想去的地方。

If you’re tidying up a huge mess, the temptation is to tear it all down and start again. Again, avoid it.

如果你在收拾一个巨大的烂摊子，诱惑就是把它全部推倒重来。同样，要抵住这种诱惑。

As far as improving documentation in-line with Diátaxis goes, it isn’t necessary to seek out things to improve.

就按照 Diátaxis 来改进文档而言，并不需要特意去搜寻待改进之处。

Instead, the best way to apply Diátaxis is as follows:

相反，应用 Diátaxis 的最佳方式如下：

Choose something - any piece of the documentation.

挑一样东西——文档中的任何一块都行。

If you don’t already have something that you know you want to put right, don’t go looking for outstanding problems.

如果你手头还没有明确想修正的东西，也别去搜寻悬而未决的问题。

Just look at what you have right in front of you at that moment: the file you’re in, the last page you read - it doesn’t matter.

就看你此刻眼前有什么：你正打开的文件、你最后读到的那一页——是什么都无所谓。

If there isn’t one just choose something, literally at random.

如果连这个都没有，那就随便挑一样，真的随机挑就行。

Assess it. Next consider this thing critically.

评估它。接下来，批判性地审视这样东西。

Preferably it’s a small thing, nothing bigger than a page - or better, even smaller, a paragraph or a sentence.

最好是个小东西，不超过一页——或者更好，再小一点，一段话或一句话。

Challenge it, according to the standards Diátaxis prescribes:

依照 Diátaxis 规定的标准来质询它：

What user need is represented by this? How well does it serve that need? What can be added, moved, removed or changed to serve that need better? Do its language and logic meet the requirements of this mode of documentation?

这里体现的是什么用户需求（user need）？它把这个需求服务得怎么样？可以增加、移动、删除或修改什么，来更好地服务这个需求？它的语言和逻辑符合这种文档模式的要求吗？

Decide what to do. Decide, based on your answers to those questions: What single next action will produce an immediate improvement here?

决定做什么。根据你对那些问题的回答来决定：接下来哪一个单一行动，能在这里立即带来改进？

Do it. Complete that next single action, and consider it completed - i.e. publish it, or at least commit the change.

去做。完成那个下一步的单一行动，并把它视作已完成——也就是发布它，或者至少提交这次修改。

Don’t feel that you need to do anything else to make a worthy improvement.

不必觉得还得再做点别的什么，这才算得上一次有价值的改进。

And then go back to the beginning of the cycle.

然后，回到循环的起点。

Working like this helps reduce the stress of one of the most paralysing and troublesome aspects of the documentation-writer’s work: working out what to do.

这样工作，有助于减轻文档写作者工作中最令人瘫痪、最麻烦的方面之一所带来的压力：琢磨该做什么。

It keeps work flowing in the right direction, always towards the desired end, without having to expend energies on a plan.

它让工作沿着正确的方向持续流动，始终朝着期望的终点前进，而无需把精力耗在一份计划上。

There’s a strong urge to work in a cycle of planning and execution in order to work towards results.

人们有一种强烈的冲动，想以“计划—执行”的循环来推进工作、追求成果。

But it’s not the only way, and there are often better ways when working with documentation.

但这不是唯一的方式；做文档工作时，往往还有更好的方式。

A good model for documentation is well-formed organic growth that adapts to external conditions.

文档的一个好模型，是顺应外部条件、形态良好的有机生长。

Organic growth takes place at the cellular level.

有机生长发生在细胞层面。

The structure of the organism as a whole is guaranteed by the healthy development of cells, according to rules that are appropriate to each kind of cell.

整个有机体的结构，由细胞的健康发育来保证——细胞按照适合各自种类的规则发育。

It’s not the other way round, that a structure is imposed on the organism from above or outside.

而不是反过来，由上方或外部把一个结构强加给有机体。

Good structure develops from within.

好的结构从内部生长出来。

Illustration copyright Linette Voller 2021, reproduced with kind permission.

插图版权归 Linette Voller 所有（2021 年），承蒙惠允转载。

It’s the same with documentation: by following the principles that Diátaxis provides, your documentation will attain a healthy structure, because its internal components themselves are well-formed - like a living organism, it will have built itself up from the inside-out, one cell at a time.

文档也是同理：遵循 Diátaxis 提供的原则，你的文档就会获得健康的结构，因为它的内部组件本身就是形态良好的——像活的有机体一样，它是由内而外、一个细胞一个细胞地把自己搭建起来的。

Consider a plant. As a living, growing organism, a plant is never finished - it can always develop further, move on to the next stage of growth and maturity.

想想一株植物。作为活着的、不断生长的有机体，植物永远没有完工——它总能继续发育，迈向生长与成熟的下一阶段。

But, at every stage of its development, from seed to a fully-mature tree, it’s always complete - there’s never something missing from it.

但在它发育的每一个阶段，从种子到完全成熟的大树，它又始终是完整的——从不缺少什么。

At any point, it is in a state that is appropriate to its stage of development.

在任何时刻，它都处于与其发育阶段相称的状态。

Similarly, documentation is also never finished, because it always has to keep adapting and changing to the product and to users’ needs, and can always be developed and improved further.

同样，文档也永远没有完工，因为它总要不断适应产品和用户（user）需求的变化并随之改变，也总能被进一步发展和改进。

However it can always be complete: useful to users, appropriate to its current stage of development, and in a healthy structural state and ready to go on to the next stage.

但它可以始终保持完整：对用户有用，与它当前的发展阶段相称，处于健康的结构状态，随时准备迈入下一阶段。

The pages in this section are intended to provide some theoretical grounding for the practices Diátaxis prescribes, and to explore some of the questions it raises.

本节各页旨在为 Diátaxis 所主张的实践提供一些理论根基，并探讨它引出的一些问题。

Within the discipline of documentation, discourse tends towards the practical and concrete.

在文档这门学科里，讨论往往偏向实用与具体。

The approach is generally heuristic: guidelines, rules of thumb, specific imperatives, principles that we know work.

方法大体上是启发式的：准则、经验法则、具体的行动指令、那些「我们知道管用」的原则。

As practitioners, we have much to say about what to do, and how to do it and how it works, and relatively little to say about why it works.

作为从业者，我们对「做什么」「怎么做」「它如何起效」有很多话说，对「它为什么起效」却说得相对很少。

Our sense of the right way to do things is largely based on a combination of intuition and experience. The theoretical aspect of the discipline receives far less attention.

我们对「正确做法」的感觉，大多建立在直觉加经验之上；这门学科的理论面向得到的关注要少得多。

Diátaxis aims to place documentation practice on a more rigorous theoretical footing.

Diátaxis 的目标，是让文档实践站上更严谨的理论地基。

These pages dig deeper into the thinking that underpins Diátaxis.

这几页深入挖掘支撑 Diátaxis 的思考。

Common problems explored:

对若干常见问题的探讨：

Diátaxis is successful because it works - both users and creators have a better experience of documentation as a result.

Diátaxis 之所以成功，是因为它管用——用户和创作者双方都因此获得了更好的文档（documentation）体验。

It makes sense and it feels right.

它讲得通，也让人觉得对路。

However, that’s not enough to be confident in Diátaxis as a theory of documentation.

然而，仅凭这一点还不足以让我们把 Diátaxis 当作一套文档理论来信赖。

As a theory, it needs to show why it works.

作为一套理论，它需要说明它为什么管用。

It needs to show that there is actually some reason why there are exactly four kinds of documentation, not three or five.

它需要证明：文档恰好有四种、而不是三种或五种，这背后确实存在某种理由。

It needs to demonstrate rigorous thinking and analysis, and that it stands on a sound theoretical foundation.

它需要展现出严谨的思考与分析，并表明自己立足于坚实的理论根基之上。

Otherwise, it will be just another useful heuristic approach, and the strongest claim we can make for it is that “it seems to work quite well”.

否则，它就只是又一种好用的启发式方法而已，我们能为它做出的最强宣称也不过是"它似乎用起来还不错"。

Diátaxis is based on the principle that documentation must serve the needs of its users.

Diátaxis 建立在这样一条原则之上：文档必须服务于其用户（user）的需求（needs）。

Knowing how to do that means understanding what the needs of users are.

要知道怎么做到这一点，就得先理解用户的需求是什么。

The user whose needs Diátaxis serves is the practitioner in a domain of skill.

Diátaxis 服务的用户，是某个技能领域中的实践者（practitioner）。

A domain of skill is defined by a craft - the use of a tool or product is a craft.

一个技能领域由一门技艺（craft）来界定——使用一件工具或一个产品就是一门技艺。

So is an entire discipline or profession.

整个学科或职业也是如此。

Using a programming language is a craft, as is flying a particular aircraft, or even being a pilot in general.

使用一门编程语言是一门技艺，驾驶某一型号的飞机是技艺，甚至广义上当一名飞行员也是技艺。

Understanding the needs of these users means in turn understanding the essential characteristics of craft or skill.

而要理解这些用户的需求，又意味着要理解技艺或技能的本质特征。

A skill or craft or practice contains both action (practical knowledge, knowing how, what we do) and cognition (theoretical knowledge, knowing that, what we think).

一项技能、技艺或实践同时包含行动（action）（实践知识，知道怎么做，我们所做的事）与认知（cognition）（理论知识，知道是什么，我们所想的事）。

The two are completely bound up with each other, but they are counterparts, wholly distinct from each other, two different aspects of the same thing.

这两者彼此完全交织在一起，但又互为对应、截然有别，是同一事物的两个不同侧面。

Similarly, the relationship of a practitioner with their practice is that it is something that needs to be both acquired, and applied.

同样地，实践者与其实践之间的关系在于：实践既需要被习得（acquisition），也需要被应用（application）。

Being “at work” (concerned with applying the skill and knowledge of their craft) and being “at study” (concerned with acquiring them) are once again counterparts, distinct but bound up with each other.

处于"工作（work）中"（关注应用其技艺的技能与知识）和处于"学习（study）中"（关注习得它们）同样互为对应，彼此有别却又相互交织。

This gives us two dimensions of skill, that we can lay out on a map - a map of the territory of craft:

这就给出了技能的两个维度，我们可以把它们铺展在一张地图（map）上——一张技艺疆域的地图：

This is a complete map.

这是一张完备的地图。

There are only two dimensions, and they don’t just cover the entire territory, they define it.

维度只有两个，而且它们不只是覆盖了整个疆域，更是界定了这片疆域。

This is why there are necessarily four quarters to it, and there could not be three, or five.

正因如此，这张地图必然分为四个象限，不可能是三个，也不可能是五个。

It is not an arbitrary number.

这不是一个随意定下的数字。

It also shows us the qualities of craft that define each of them.

这张地图还向我们展示了界定每个象限的技艺品质（quality）。

When the idea that documentation must serve the needs of craft is applied to this map, it reveals in turn what documentation must be and do to fulfil those obligations - in four distinct ways.

当"文档必须服务于技艺的需求"这一理念被应用到这张地图上时，它便进而揭示出：文档要履行这些义务，必须成为什么、做到什么——并且是以四种彼此不同的方式。

The map of the territory of craft is what gives us the familiar Diátaxis map of documentation.

正是这张技艺疆域的地图，给出了我们熟悉的 Diátaxis 文档地图。

The map is in effect an answer to the question: what must documentation do to align with these qualities of skill, and to what need is it oriented in each case?

这张地图实际上回答了这样一个问题：文档必须做什么，才能与技能的这些品质对齐？在每种情形下，它又是面向哪种需求的？

We can see how the map of documentation addresses needs across those two dimensions, each need also defined by the characteristics of its quarter of the map.

我们可以看到，文档地图如何在这两个维度上回应各种需求，每种需求同样由它所在象限的特征所界定。

The Diátaxis map of documentation is a memorable and approachable idea.

Diátaxis 文档地图是一个易记又易懂的想法。

But, a map is only reliable if it adequately describes a reality.

但是，一张地图只有充分描述了某种现实，才算可靠。

Diátaxis is underpinned by a systematic description and analysis of generalised user needs.

Diátaxis 的底层支撑，是对普遍化的用户需求所做的系统性描述与分析。

This is why the tutorials, how-to guides, reference and explanation of Diátaxis are a complete enumeration of the types of documentation that serve practitioners in a craft.

正因如此，Diátaxis 的教程、操作指南、参考和阐释，是对服务于技艺实践者的文档类型的一次完备枚举。

This is why there are four and only four types of documentation.

正因如此，文档类型有且只有四种。

There is simply no other territory to cover.

除此之外，根本没有其他疆域需要覆盖。

One reason Diátaxis is effective as a guide to organising documentation is that it describes a two-dimensional structure, rather than a list.

Diátaxis 之所以能有效指导文档（documentation）的组织，一个原因在于它描述的是一个二维结构，而不是一个清单。

It specifies its types of documentation in such a way that the structure naturally helps guide and shape the material it contains.

它对文档类型的界定方式，使得这个结构天然地帮助引导和塑造其中所容纳的材料。

As a map, it places the different forms of documentation into relationships with each other.

作为一张地图（map），它把不同形态的文档置入彼此的关系之中。

Each one occupies a space in the mental territory it outlines, and the boundaries between them highlight their distinctions.

每一种形态都在它勾勒出的心智版图中占据一块空间，而它们之间的边界凸显出彼此的区别。

When documentation fails to attain a good structure, it’s rarely just a problem of structure (though it’s bad enough that it makes it harder to use and maintain).

当文档未能获得良好的结构时，问题很少只停留在结构层面（尽管仅这一点就够糟了——它会让文档更难使用、更难维护）。

Architectural faults infect and undermine content too.

架构上的缺陷还会感染并侵蚀内容本身。

In the absence of a clear, generalised documentation architecture, documentation creators will often try to structure their work around features of a product.

在缺乏清晰、通用的文档架构时，文档创作者往往会试图围绕产品的功能特性来组织自己的工作。

This is rarely successful, even in a single instance.

这种做法很少成功，哪怕只用在单个文档实例上。

In a portfolio of documentation instances, the results are wild inconsistency.

而在一组文档实例的组合中，其结果就是严重的不一致。

Much better is the adoption of a scheme that tries to provide an answer to the question: how to arrange documentation in general?

远为可取的做法，是采用一套试图回答这个问题的方案：一般而言，文档应当如何编排？

In fact any orderly attempt to organise documentation into clear content categories will help improve it (for authors as well as users), by providing lists of content types.

事实上，任何把文档有条理地组织进清晰内容类别的尝试，都会通过提供内容类型清单而使文档得到改善（对作者和用户都是如此）。

Even so, authors often find themselves needing to write particular documentation content that fails to fit well within the categories put forward by a scheme, or struggling to rewrite existing material.

即便如此，作者们仍常常发现自己要写的某些文档内容无法很好地纳入某套方案所提出的类别，或者在改写已有材料时苦苦挣扎。

Often, there is a sense of arbitrariness about the structure that they find themselves working with - why this particular list of content types rather than another?

他们所面对的结构常常带着一种任意感——为什么偏偏是这份内容类型清单，而不是另一份？

And if another competing list is proposed, which to adopt?

而如果又有人提出另一份与之竞争的清单，该采用哪一份？

A clear advantage of organising material this way is that it provides both clear expectations (to the reader) and guidance (to the author).

以这种方式组织材料有一个明显的优势：它既给读者提供了清晰的预期，也给作者提供了引导。

It’s clear what the purpose of any particular piece of content is, it specifies how it should be written and it shows where it should be placed.

任何一段内容的目的是什么一目了然，它规定了该怎么写，也指明了该放在哪里。

Each piece of content is of a kind that not only has one particular job to do, that job is also clearly distinguished from and contrasted with the other functions of documentation.

每一段内容都归属于某个类型——这个类型不仅有一项特定的工作要做，而且这项工作与文档的其他功能之间界限分明、彼此对照。

Most documentation systems and authors recognise at least some of these distinctions and try to observe them in practice.

大多数文档体系和作者至少能认识到其中的一部分区别，并试图在实践中加以遵守。

However, there is a kind of natural affinity between each of the different forms of documentation and its neighbours on the map, and a natural tendency to blur the distinctions (that can be seen repeatedly in examples of documentation).

然而，每种文档形态与它在地图上的邻居之间存在某种天然的亲缘性，也存在一种把区别模糊掉的天然倾向（这在文档的实例中屡见不鲜）。

When these distinctions are allowed to blur, the different kinds of documentation bleed into each other.

一旦放任这些区别模糊化，不同种类的文档就会互相渗透。

Writing style and content make their way into inappropriate places.

写作风格和内容会流窜到不该出现的地方。

It also causes structural problems, which make it even more difficult to maintain the discipline of appropriate writing.

这还会引发结构问题，使得恰当写作的纪律更加难以维持。

In the worst case there is a complete or partial collapse of tutorials and how-to guides into each other, making it impossible to meet the needs served by either.

最糟的情形是，教程与操作指南彻底或部分地塌缩到一起，使得两者各自要满足的需求（needs）都无法得到满足。

Diátaxis is intended to help documentation better serve users in their cycle of interaction with a product.

Diátaxis 的用意，是帮助文档更好地服务于用户（user）与产品之间的交互循环。

This phrase should not be understood too literally.

这个说法不应理解得过于字面。

It is not the case that a user must encounter the different kinds of documentation in the order tutorials > how-to guides > technical reference > explanation.

并不是说用户必须按照教程 > 操作指南 > 技术参考 > 阐释的顺序去接触各类文档。

In practice, an actual user may enter the documentation anywhere in search of guidance on some particular subject, and what they want to read will change from moment to moment as they use your documentation.

实际中，真实的用户可能从任何地方进入文档，寻找关于某个特定主题的指引；而且在使用你的文档的过程中，他们想读的东西也会随时变化。

However, the idea of a cycle of documentation needs, that proceeds through different phases, is sound and corresponds to the way that people actually do become expert in a craft.

不过，「文档需求循环」这个想法——它经历不同阶段依次推进——是站得住脚的，而且与人们在一门技艺（craft）上真正走向精通的方式相吻合。

There is a sense and meaning to this ordering.

这个次序自有其道理与意义。

And then it’s back to the beginning, perhaps for a new thing to grasp, or to penetrate deeper.

然后又回到起点——也许是为了掌握一件新东西，也许是为了钻研得更深。

Diátaxis is an approach to quality in documentation.

Diátaxis 是一种追求文档（documentation）品质（quality）的方法。

“Quality” is a word in danger of losing some of its meaning; it’s something we all approve of, but rarely risk trying to describe in any rigorous way.

「品质」这个词正面临失去部分含义的危险；它是我们人人都赞同的东西，却很少有人敢尝试严格地描述它。

We want quality in our documentation, but much less often specify what exactly we mean by that.

我们希望自己的文档有品质，却远远更少去明确说明我们所指的究竟是什么。

All the same, we can generally point to examples of “high-quality documentation” when asked, and can identify lapses in quality when we see them - and more than that, we often agree when we do.

尽管如此，当被问起时，我们通常还是能指出「高品质文档」的例子，也能在看到品质缺陷时把它们辨认出来——不仅如此，我们的判断往往还彼此一致。

This suggests that we still have a useful grasp on the notion of quality.

这说明我们对品质这一概念仍然握有一种可用的把握。

As we pursue quality in documentation, it helps to make that grasp surer, by paying some attention to it - here, attempting to refine our grasp by positing a distinction between functional quality and deep quality.

在追求文档品质的过程中，对这种把握投入一些注意、让它变得更牢靠，会很有帮助——在这里，我们尝试通过提出功能性品质（functional quality）与深层品质（deep quality）的区分，来打磨这种把握。

We need documentation to meet standards of accuracy, completeness, consistency, usefulness, precision and so on.

我们需要文档达到准确性、完整性、一致性、有用性、精确性等标准。

We can call these aspects of its functional quality.

我们可以把这些称为文档功能性品质的诸方面。

Documentation that fails to meet any one of them is failing to perform one of its key functions.

未能满足其中任何一项的文档，就是未能履行它的一项关键职能。

These properties of functional quality are all independent of each other.

功能性品质的这些属性彼此完全独立。

Documentation can be accurate without being complete.

文档可以准确而不完整。

It can be complete, but inaccurate and inconsistent.

也可以完整，却不准确、不一致。

It can be accurate, complete, consistent and also useless.

还可以既准确、完整、一致，同时又毫无用处。

Attaining functional quality means meeting high, objectively-measurable standards in multiple independent dimensions, consistently.

达到功能性品质，意味着在多个相互独立的维度上持续满足客观可测的高标准。

It requires discipline and attention to detail, and high levels of technical skill.

这需要自律、对细节的关注，以及高水平的技术能力。

To make it harder for the creator of documentation, any failure to meet all of these standards is readily apparent to the user.

更让文档创作者为难的是，这些标准中只要有任何一项没有达到，用户（user）都能一眼看出。

There are other characteristics, that we can call deep quality.

还有另外一些特征，我们可以称之为深层品质。

Functional quality is not enough, or even satisfactory on its own as an ambition.

功能性品质并不足够，甚至单独作为一种追求目标也难以令人满意。

True excellence in documentation implies characteristics of quality that are not included in accuracy, completeness and so on.

文档的真正卓越，意味着一些并不包含在准确性、完整性等之内的品质特征。

Think of characteristics such as:

想想这样一些特征：

Unlike the characteristics of functional quality, they cannot be checked or measured, but they can still be clearly identified.

与功能性品质的特征不同，它们无法被检验或测量，但仍然能被清楚地辨认出来。

When we encounter them, we usually (not always, because we need to be capable of it) recognise them.

当我们遇到它们时，通常（不是总能，因为这需要我们具备相应的能力）能够认出它们。

They are characteristics of deep quality.

它们就是深层品质的特征。

Aspects of deep quality seem to be genuinely distinct in kind from the characteristics of functional quality.

深层品质的诸方面，看起来与功能性品质的特征在类别上确有真正的不同。

Documentation can meet all the demands of functional quality, and still fail to exhibit deep quality.

文档可以满足功能性品质的全部要求，却仍然展现不出深层品质。

There are many examples of documentation that is accurate and consistent (and even very useful) but which is also awkward and unpleasant to use.

有很多这样的文档例子：既准确又一致（甚至非常有用），用起来却又别扭又不愉快。

It’s also noticeable that while characteristics of functional quality such as completeness and accuracy are independent of each other, those of deep quality are hard to disentangle.

还有一点值得注意：完整性、准确性等功能性品质的特征彼此独立，而深层品质的特征却难以拆解开来。

Having flow and anticipating the user are aspects of each other - they are interdependent.

具有心流与预判用户所需互为表里——它们是相互依存的。

It’s hard to see how something could feel good to use without fitting to our needs.

很难想象一样东西不贴合我们的需求，用起来却还能感觉很好。

Aspects of functional quality can be measured - literally, with numbers, in some cases (consider completeness).

功能性品质的诸方面可以被测量——在某些情形下（想想完整性）真的可以用数字来量。

That’s clearly not possible with qualities such as having flow.

对「具有心流」这类品质，这显然做不到。

Instead, such qualities can only be enquired into, interrogated.

相反，这类品质只能被探询、被叩问。

Instead of taking measurements, we must make judgements.

我们不能做测量，而必须下判断。

Functional quality is objective - it belongs to the world.

功能性品质是客观的——它属于世界。

Accuracy of documentation means the extent to which it conforms to the world it’s trying to describe.

文档的准确性，指的是它与它试图描述的那个世界相符合的程度。

Deep quality can’t be ascertained by holding something up to the world.

深层品质无法通过把东西举到世界面前对照来确定。

It’s subjective, which means that we can assess it only in the light of the needs of the subject of experience, the human.

它是主观的，这意味着我们只能依照体验主体——人——的需求来评估它。

And, deep quality is conditional upon functional quality.

而且，深层品质以功能性品质为条件。

Documentation can be accurate and complete and consistent without being truly excellent - but it will never have deep quality without being accurate and complete and consistent.

文档可以准确、完整、一致却算不上真正卓越——但若不准确、不完整、不一致，它就永远不会拥有深层品质。

No user of documentation will experience it as beautiful, if it’s inaccurate, or enjoy the way it anticipates their needs if it’s inconsistent.

如果文档不准确，没有用户会体验到它的美；如果它不一致，也没有人会享受它预判自己需求的方式。

The moment we run into such lapses the experience of documentation is tarnished.

一旦撞上这类缺陷，文档的使用体验就被玷污了。

Finally, all of the characteristics of functional quality appear to us, as documentation creators, as burdens and constraints.

最后，对我们这些文档创作者来说，功能性品质的所有特征都呈现为负担和约束。

Each one of them represents a test or challenge we might fail.

其中每一项都代表一场我们可能通不过的考验或挑战。

Or, even if we have met one now, we can never rest, because the next release or update means that we’ll have to check our work once again, against the thing that it’s documenting.

或者说，即便此刻我们达到了某项标准，也永远不能松懈，因为下一次发布或更新，就意味着我们必须再次对照所记录的对象核查自己的工作。

Characteristics such as anticipating needs or flow, on the other hand, represent liberation, the work of creativity or taste.

而预判需求、心流这类特征则代表解放，是创造力或品味的功课。

To attain functional quality in our work, we must conform to constraints; to attain deep quality we must invent.

要在工作中达到功能性品质，我们必须服从约束；要达到深层品质，我们必须去创造。

Consider how we judge the quality of say, clothing.

想想我们如何评判——比如说——衣物的品质。

Clothes must have functional quality (they must keep us appropriately warm and dry, stand up to wear).

衣物必须具备功能性品质（要能恰当地保暖挡水，经得起穿着磨损）。

These things are objectively measurable.

这些都是客观可测的。

You don’t really need to know much about clothes to assess how well they do those things.

评估衣物在这些方面做得如何，其实不需要懂多少衣物知识。

If water gets in, or the clothing falls apart - it lacks quality.

如果水渗进来了，或者衣服散架了——那它就缺乏品质。

There are other characteristics of quality in clothing that can’t simply be measured objectively, and to recognise those characteristics, we need to have an understanding of clothing.

衣物还有一些品质特征无法简单地客观测量，要辨认这些特征，我们需要对衣物有所理解。

The quality of materials or workmanship isn’t always immediately obvious.

用料或做工的品质并不总是一眼可见。

Being able to judge that an item of clothing hangs well, moves well or has been expertly shaped requires developing at least a basic eye for those things.

要能判断一件衣服垂坠得好、随动得好，或者剪裁塑形出自行家之手，至少需要先练出一点这方面的基本眼力。

And these are its characteristics of deep quality.

而这些正是它的深层品质特征。

But: even someone who can’t recognise, or fails to understand, those characteristics - who cannot say what they are - can still recognise very well that the clothing is excellent, because they find it that it feels good to wear, because it’s such that they want to wear it.

但是：即便有人认不出、或者理解不了这些特征——说不出它们是什么——也仍然能清清楚楚地认出这件衣服确实出色，因为他们发现它穿起来感觉很好，因为它就是让人想穿。

No expertise is required to realise that clothing does or doesn’t feel comfortable as you move in it, that it fits and moves with you well.

要察觉一件衣服在你活动时穿着舒不舒服、是否合身并随你而动，不需要任何专业知识。

Your body knows it.

你的身体知道。

And it’s the same in documentation.

文档也是同样的道理。

Perhaps you need to be a connoisseur to recognise what it is that makes some documentation excellent, but that’s not necessary to be able to realise that it is excellent.

也许你需要是个行家，才能认出是什么让某份文档出色，但要察觉到它确实出色，并不需要如此。

Good documentation feels good; you feel pleasure and satisfaction when you use it - it feels like it fits and moves with you.

好的文档让人感觉很好；使用它时你会感到愉悦和满足——它感觉像是合着你的身、随着你而动。

The users of our documentation may or may not have the understanding to say why it’s good, or where its quality lapses.

我们文档的用户，可能有、也可能没有那种能说出它为何好、品质缺陷在哪里的理解力。

They might recognise only the more obvious aspects of functional quality in it, mistaking those for its deeper excellence.

他们也许只认得出其中较为明显的功能性品质方面，把那些误当作它更深层的卓越。

That doesn’t matter - it will feel good, or not, and that’s what is important.

这没有关系——它用起来要么感觉好，要么不好，这才是重要的。

But we, as its creators, need a clear and effective understanding of what makes documentation good.

但作为文档的创作者，我们需要对是什么让文档变好有一种清晰而有效的理解。

We need to develop our sense of it so that we recognise what is good about it, as well as that it is good.

我们需要培养这方面的感觉，既能认出它好在哪里，也能认出它确实好。

And we need to develop an understanding of how people will feel when they’re using it.

我们还需要建立起一种理解：人们在使用它的时候会有什么感受。

Producing work of deep quality depends on our ability to do this.

能否产出具有深层品质的作品，取决于我们做到这一点的能力。

Functional quality’s obligations are met through conscientious observance of the demands of the craft of documentation.

功能性品质的义务，要靠尽责地遵从文档这门技艺（craft）的要求来履行。

They require solid skill and knowledge of the technical domain, the ability to gather up a complete terrain into a single, coherent, consistent map of it.

这需要扎实的技能和对技术领域的了解，需要那种把一整片地形收拢成一张连贯、一致的单一地图（map）的能力。

Diátaxis cannot address functional quality in documentation.

Diátaxis 无法解决文档的功能性品质问题。

It is concerned only with certain aspects of deep quality, some more than others - though if all the aspects of deep quality are tangled up in each other, then it affects all of them.

它只关心深层品质的某些方面，且各有轻重——不过，既然深层品质的各个方面彼此纠缠，那么它也就影响到所有这些方面。

Although Diátaxis cannot address, or give us, functional quality, it can still serve it.

虽然 Diátaxis 无法解决功能性品质问题，也无法把功能性品质给到我们，但它仍然可以为其效力。

It works very effectively to expose lapses in functional quality.

它在揭露功能性品质缺陷方面非常有效。

It’s often remarked that one effect of applying Diátaxis to existing documentation is that problems in it suddenly become apparent that were obscured before.

人们常常提到，把 Diátaxis 应用到既有文档上的一个效果，就是其中先前被遮蔽的问题突然显形。

For example: the Diátaxis approach recommends that the architecture of reference documentation should reflect the architecture of the code it documents.

例如：Diátaxis 方法建议，参考（reference）文档的架构应当映照它所记录的代码的架构。

This makes gaps in the documentation much more clearly visible.

这会让文档中的缺口清楚可见得多。

Or, moving explanatory verbiage out of a tutorial (in accordance with Diátaxis demands) often has the effect of highlighting a section where the reader has been left to work something out for themselves.

又如，（按照 Diátaxis 的要求）把阐释性的冗词移出教程（tutorial），常常会凸显出某个读者被丢下自行摸索的段落。

But, as far as functional quality goes, Diátaxis principles can have only an analytical role.

但就功能性品质而言，Diátaxis 的原则只能起到分析性的作用。

In deep quality on the other hand, the Diátaxis approach can do more.

而在深层品质上，Diátaxis 方法能做的就更多了。

For example, it helps documentation fit user needs by describing documentation modes that are based on them; its categories exist as a response to needs.

例如，它通过描述以用户需求为基础的文档模式，帮助文档贴合用户需求；它的各个类别正是作为对需求的回应而存在的。

We must pay attention to the correct organisation of these categories then, and the arrangement of its material and the relationships within them, the form and language adopted in different parts of documentation - as a way of fitting to user needs.

那么，我们就必须留意这些类别的正确组织，留意其中材料的编排及其内部的关系，留意文档不同部分所采用的形式和语言——以此作为贴合用户需求的途径。

Or, in Diátaxis we are directly concerned with flow.

又如，在 Diátaxis 中，我们直接关切心流。

In flow - whether the context is documentation or anything else - we experience a movement from one stage or state to another that seems right, unforced and in sympathy with both our concerns of the moment, and the way our minds and bodies work in general.

在心流之中——无论情境是文档还是别的什么——我们体验到从一个阶段或状态到另一个阶段或状态的移动，这种移动感觉恰到好处、毫不勉强，既与我们当下的关切相合，也与我们身心运作的一般方式相合。

Diátaxis preserves flow by helping prevent the kind of disruption of rhythm that occurs when something runs across our purpose and steady progress towards it (for example when a digression into explanation interrupts a how-to guide).

Diátaxis 通过帮助防止那种节奏被打断的情况来保全心流——当某样东西横插进我们的目的以及朝向目的的稳步推进时，节奏就会被打断（例如，当一段跑去阐释（explanation）的岔话打断了一篇操作指南（how-to guide）时）。

And so on.

诸如此类。

It’s important to understand that Diátaxis can never be all that is required in the pursuit of deep quality.

重要的是要明白：在追求深层品质的路上，Diátaxis 永远不可能是所需的全部。

For example, while it can help attain beauty in documentation, at least in its overall form, it doesn’t by itself make documentation beautiful.

例如，它虽然能帮助文档获得美感——至少在整体形态上——但它本身并不能让文档变美。

Diátaxis offers a set of principles - it doesn’t offer a formula.

Diátaxis 提供的是一组原则——而不是一个公式。

It certainly cannot offer a short-cut to success, bypassing the skills and insights of disciplines such as user experience or user interaction design, or even visual design.

它当然更不能提供一条成功的捷径，让人绕开用户体验、用户交互设计乃至视觉设计等学科的技能与洞见。

Using Diátaxis does not guarantee deep quality.

使用 Diátaxis 并不能保证深层品质。

The characteristics of deep quality are forever being renegotiated, reinterpreted, rediscovered and reinvented.

深层品质的特征，永远处在被重新商定、重新诠释、重新发现和重新发明之中。

But what Diátaxis can do is lay down some conditions for the possibility of deep quality in documentation.

但 Diátaxis 能做的，是为文档深层品质的可能性铺设一些条件。

In Diátaxis, tutorials and how-to guides are strongly distinguished.

在 Diátaxis 中，教程（tutorial）与操作指南（how-to guide）被严格区分开来。

It’s a distinction that’s often not made; in fact the single most common conflation made in software product documentation is that between the tutorial and the how-to guide.

这一区分常常没有被做出；事实上，软件产品文档（documentation）中最常见的一种混淆，就是教程与操作指南之间的混淆。

So: what is the difference between tutorials and how to-guides? Why does it matter? And why do they get confused?

那么：教程和操作指南的区别究竟是什么？为什么这很重要？又为什么它们会被混淆？

These are all good questions. Let’s start with the last one.

这些都是好问题。我们从最后一个开始。

If the distinction is really so important, why isn’t it more obvious?

如果这一区分真的如此重要，为什么它不更明显一些？

In important respects, tutorials and how-to guides are indeed similar.

在一些重要方面，教程和操作指南确实相似。

They are both practical guides: they contain directions for the user to follow.

它们都是实践性的指引：都包含供用户（user）遵循的指示。

They’re not there to explain or convey information.

它们的存在不是为了阐释或传递信息。

They exist to guide the user in what to do rather than what there is to know or understand.

它们的存在是为了指引用户去做什么，而不是告诉用户有什么可知道、可理解的。

They both set out steps for the reader to follow, and they both promise that if the reader follows those steps, they’ll arrive at a successful conclusion.

两者都列出供读者遵循的步骤，也都承诺：只要读者照着这些步骤做，就会到达一个成功的结局。

Neither of them make much sense except for the user who has their hands on the machinery, ready to do things.

除非用户已经把手放在机器上、准备动手做事，否则它们二者都没有多大意义。

They both describe ordered sequences of actions.

它们都描述有顺序的行动（action）序列。

You can’t expect success unless you perform the actions in the right order.

不按正确的顺序执行这些行动，就别指望成功。

They are closely related, and like many close relations, can be mistaken for one another at first glance.

它们是近亲，而正如许多近亲一样，乍一看会被认成彼此。

Diátaxis insists that what matters in documentation is the needs of the user, and it’s by paying attention to this that we can correctly distinguish between tutorials and how-to guides.

Diátaxis 坚持认为，文档中要紧的是用户的需求（needs），而正是通过关注这一点，我们才能正确区分教程与操作指南。

Sometimes the user is at study, and sometimes the user is at work.

用户有时处于学习（study）之中，有时处于工作（work）之中。

Documentation has to serve both those needs.

文档必须同时服务这两种需求。

A tutorial serves the needs of the user who is at study.

教程服务的是处于学习中的用户的需求。

Its obligation is to provide a successful learning experience.

它的义务是提供一次成功的学习体验。

A how-to guide serves the needs of the user who is at work.

操作指南服务的是处于工作中的用户的需求。

Its obligation is to help the user accomplish a task.

它的义务是帮助用户完成一项任务。

These are completely different needs and obligations, and they are why the distinction between tutorials and how-to guides matters: tutorials are learning-oriented, and how-to guides are task-oriented.

这是两种完全不同的需求和义务，也正是教程与操作指南之分之所以重要的原因：教程是以学习为导向的（learning-oriented），操作指南是以任务为导向的（task-oriented）。

We can consider this from the perspective of an actual example.

我们可以借一个实际的例子来考虑这一点。

Let’s say you’re in medicine: a doctor, someone who needs to acquire and apply the practical, clinical skills of their craft.

假设你身在医学界：一名医生，需要习得（acquire）并应用（apply）自己这门技艺（craft）中实践性的临床技能。

As a doctor, sometimes you will be in work situations, applying your skills, and sometimes you will be in study situations, acquiring skills (all good doctors, even those with long careers behind them, continue to study to improve their skills).

作为医生，你有时会处于工作情境中，应用你的技能；有时会处于学习情境中，习得技能（所有好医生——即便是从业多年的老医生——都会持续学习以精进技能）。

Early on in your training, you’ll learn how to suture a wound.

在训练早期，你会学习如何缝合伤口。

You’ll start in the lab with your fellow students, at benches with small skin pads in front of you (skin pads are blocks of synthetic material in various layers that represent the epidermis, fat and other tissues. They have a similar hardness and texture to human flesh, and behave somewhat similarly when they’re cut and stitched).

你会和同学们一起从实验室开始，站在操作台前，面前放着小块皮肤垫（皮肤垫是分成多层的合成材料块，用来代表表皮、脂肪等各种组织。它们的硬度和质感与人体肌肤相近，被切开和缝合时的表现也有几分相似）。

You’ll be provided with exactly what you need - gloves, scalpel, needle, thread and so on - and step-by-step you’ll be shown what to do, and what will happen when you do it.

你需要的东西——手套、手术刀、缝针、缝线等等——都会为你备好，然后有人会一步一步向你演示该做什么，以及做了之后会发生什么。

And then it’s your turn.

然后轮到你了。

You will pick up the scalpel and tentatively draw it across the top of the pad, and make an ineffectual incision into the top layer (maybe a teaching assistant will tease you, asking what this poor pad has done, that it deserves such a nasty scratch).

你会拿起手术刀，小心翼翼地在皮肤垫表面划过，在最上层划出一道没什么用的切口（也许助教会打趣你，问这块可怜的皮肤垫做错了什么，要挨这么难看的一道抓痕）。

Your neighbour will look dismayed at their own attempt, a ragged cut of wildly uneven depths that looks like something from a knife-fight.

你旁边的同学则会对自己的成果面露沮丧——一道深浅极不均匀的粗糙切口，看起来像斗殴留下的刀伤。

After a few attempts, with feedback and correction from the tutor, you’ll have made a more or less clean cut that mostly goes through the fat layer without cutting into the muscle beneath. Triumph!

尝试几次之后，在导师的反馈和纠正下，你会切出一道大体干净的切口，基本穿过脂肪层，而没有切进下面的肌肉。大功告成！

But now you’re being asked to stitch it back up again!

但现在，你又被要求把它缝回去！

You’ll watch the tutor demonstrate deftly and precisely, closing the wound in the pad with a few neat, even stitches.

你会看着导师娴熟而精准地示范，用几针整齐匀称的缝线把皮肤垫上的伤口合拢。

You, on the other hand, will fumble with the thread.

而你呢，则会被缝线弄得手忙脚乱。

You will hold things in the wrong hand and the wrong way round and put them down in the wrong places.

你会用错手拿东西、拿反方向，还会把东西放错地方。

You will drop the needle. The thread will fall out.

你会把针掉在地上。线会脱出来。

You will be told off for failing to maintain sterility.

你还会因为没能保持无菌而挨批评。

Eventually, you’ll actually get to stitch the wound.

最终，你总算真正开始缝合伤口。

You will puncture the skin in the wrong places and tear the edges of the cut.

你会在错误的位置扎穿皮肤，扯裂切口的边缘。

Your final result will be an ugly scene of stretched and puckered skin and crude, untidy stitches.

你的最终成果将是一片惨状：皮肤被拉扯得起皱变形，缝线粗糙凌乱。

The teaching assistants will have some critical things to say even about parts of it that you thought you’d got right.

就连你自以为做对了的部分，助教们也会挑出一些毛病来。

But, you will have stitched your first wound.

但是，你已经缝合了你的第一道伤口。

And you will come back to this lesson again and again, and bit by bit your fumbling will turn into confident practice.

而且你会一次又一次回到这堂课上来，你的笨手笨脚会一点一点变成自信的操作。

You will have acquired basic competence. You will have learned by doing.

你将习得基本的胜任力。你将在做中学会。

This is a tutorial. It’s a lesson, safely in the hands of an instructor, a teacher who looks after the interests of a pupil.

这就是教程。它是一堂课，安稳地交在指导者手中——一位照看学生利益的老师。

Now, let’s think about the doctor at work. As a doctor at work, you are already competent.

现在，我们来想想工作中的医生。作为工作中的医生，你已经具备胜任力。

You have learned and refined clinical skills such as suturing, as well as many others, and you’re able to put them together on a daily basis to apply them to medical situations in the real world.

你已经学会并磨炼了缝合等临床技能，还有许多其他技能，并且每天都能把它们组合起来，应用到真实世界的医疗情境中。

Consider a standard appendectomy. A clinical manual will list the equipment and personnel required in the theatre.

想想一台标准的阑尾切除术。临床手册会列出手术室所需的设备和人员。

It will show how to station the members of the team, and how to lay out the required tools, stands and monitors.

它会说明如何安排团队成员的站位，如何摆放所需的器械、支架和监护仪。

It will proceed step-by-step through the actions the team will need to follow, ending with the formal handover to the post-operative team.

它会一步一步列出团队需要执行的行动，直到正式移交给术后团队为止。

The manual will show what incisions need to be made where, but they will depend on whether you’re performing an open or a laparoscopic procedure, whether you have pre-operative imaging to rely on or not, and so on.

手册会说明需要在哪里做什么样的切口，但这取决于你做的是开腹手术还是腹腔镜手术、有没有术前影像可以依靠，等等。

It will include special steps or checks to be made in the case of an infant or juvenile patient, or when converting to an open appendectomy mid-procedure.

它还会包含针对婴幼儿或未成年患者、或术中转为开腹阑尾切除时需要执行的特殊步骤或检查。

Many of the steps will be of the form if this, then that.

许多步骤都是如果这样，就那样的形式。

Having a manual helps ensure that all the steps are done in the right order and none are omitted.

有一本手册在手，有助于确保所有步骤按正确顺序完成、一步不漏。

As a team, you’ll check through details of a procedure to remind yourselves of key steps; sometimes you’ll refer to it during the procedure itself.

作为一个团队，你们会核对手术流程的细节来提醒自己关键步骤；有时你们还会在手术进行当中查阅它。

Even for routine surgical operations, clinical manuals contain lists of steps and checks. These manuals are how-to guides.

即使是常规的外科手术，临床手册也包含步骤和检查的清单。这些手册就是操作指南。

They are not there to teach you - you already have your skills. You already know these processes.

它们不是用来教你的——你已经拥有自己的技能。这些流程你早已了然。

They are there to guide you safely in your clinical practice to accomplish a particular task - they serve your work.

它们的存在，是为了在你的临床实践中安全地指引你完成一项特定任务——它们服务于你的工作。

The distinction between a lesson in medical school and a clinical manual is the distinction between a tutorial and a how-to guide.

医学院里的一堂课与一本临床手册之间的区分，就是教程与操作指南之间的区分。

None of these distinctions are arbitrary.

这些区分没有一条是任意武断的。

They all emerge from the distinction between study and work, which we understand as a key distinction in making sense of what the user of documentation needs.

它们全都源自学习与工作之间的区分——在我们看来，这是理解文档用户需求的一个关键区分。

A common but understandable conflation is to see the difference between tutorials and how-to guides as being the difference between the basic and the advanced.

一种常见但可以理解的混淆，是把教程与操作指南的区别看成基础与高级的区别。

After all, tutorials are for learners, while how-to guides are for already-skilled practitioners.

毕竟，教程面向学习者，而操作指南面向已经掌握技能的从业者。

Tutorials must cover the basics, while how-to guides have to deal with complexities that learners should not have to face.

教程必须涵盖基础内容，而操作指南则要处理学习者本不该面对的复杂情况。

However, there’s more to the story. Consider a clinical procedure manual: it could be a manual for a basic routine procedure, of very low complexity.

然而，事情并非仅此而已。想想一本临床操作手册：它可能是一本讲基础常规操作的手册，复杂度非常低。

It could describe steps for mundane matters such as correct completion of paperwork or disposal of particular materials.

它描述的可能是些平凡琐事的步骤，比如如何正确填写文书、如何处置特定材料。

How-to guides can, do and often should cover basic procedures.

操作指南可以覆盖、也确实在覆盖、而且往往应该覆盖基础操作。

At the same time, even as a qualified doctor, you will find yourself back in training situations.

与此同时，即使已是一名合格的医生，你也会发现自己重新回到训练情境中。

Some of them may be very advanced and specialised, requiring a high level of skill and expertise already.

其中一些训练可能非常高级、非常专门，本身就要求很高的技能和专业水平。

Let’s say you’re an anaesthetist of many years’ experience, who attends a course: “Difficult neonatal intubations”.

假设你是一位有多年经验的麻醉师，去参加一门课程："新生儿困难插管"。

The practical part of the course will be a learning experience: a lesson, safely in the hands of the instructors, that will have you performing particular exercises to develop your skills - just as it was when years earlier, you were learning to suture your first wound.

课程的实操部分将是一次学习体验：一堂课，安稳地交在指导者手中，让你通过特定的练习来发展技能——正如多年以前，你学着缝合第一道伤口时那样。

The complexity is wholly different though, and so is the baseline of skills required even to participate in the learning experience.

不过其复杂度已完全不同，连参与这次学习体验所需的技能起点也完全不同。

But, it’s of the same form, and serves the same kind of need, as that much earlier lesson.

但它与多年前那堂课形式相同，服务的也是同一类需求。

It’s the same in software documentation: a tutorial can present something complex or advanced.

软件文档中也是同理：教程可以呈现复杂或高级的内容。

And, a how-to guide can cover something that’s basic or well-known.

而操作指南也可以覆盖基础的或人尽皆知的内容。

The difference between the two lies in the need they serve: the user’s study, or their work.

二者的区别在于它们所服务的需求：用户的学习，还是用户的工作。

Understanding these distinctions, and the reason for upholding them, is crucial to creating successful documentation.

理解这些区分，以及坚守它们的理由，对创作成功的文档至关重要。

A clinical manual that conflated education with practice, that tried to teach while at the same time providing a guide to a real-world procedure would be a literally deadly document. It would kill people.

一本把教育与实践混为一谈的临床手册——一边试图教学、一边又为真实世界的手术提供指引——将是一份字面意义上的致命文档。它会害死人。

In disciplines such as software documentation, we get away with a great deal, because our conflations and mistakes rarely kill anyone.

在软件文档这类领域，我们侥幸逃过了很多，因为我们的混淆和错误很少害死人。

However, we can cause a great deal of low-level inconvenience and unhappiness to our users, and we add to it, every single time we publish a tutorial or how-to guide that doesn’t understand whether its purpose is to help the user in their study - the acquisition of skills - or in their work - the application of skills.

然而，我们会给用户造成大量低强度的不便与不快；而且每当我们发布一篇分不清自己目的的教程或操作指南——不清楚自己是要帮助用户学习（技能的习得），还是帮助用户工作（技能的应用）——我们就在往这堆不快上再添一笔。

What’s more, we hurt ourselves too. Users don’t have to use our product.

更有甚者，我们也在伤害自己。用户并非非用我们的产品不可。

If our documentation doesn’t bring them to success - if it doesn’t meet the needs that they have at a particular stage in their cycle of interaction with our product - they will find something else that does, if they can.

如果我们的文档不能把他们带向成功——如果它满足不了他们在与产品互动周期的某个特定阶段所抱有的需求——只要有可能，他们就会去找别的能满足需求的东西。

The conflation of tutorials and how-to guides is by no means the only one made between different kinds of documentation, but it’s one of the easiest to make.

教程与操作指南的混淆，绝不是不同文档类型之间唯一的混淆，但它是最容易犯的混淆之一。

It’s also a particularly harmful one, because it risks getting in the way of those newcomers whom we hope to turn into committed users.

它也格外有害，因为它可能挡住那些我们希望转化为忠实用户的新人的路。

For the sake of those users, and of our own product, getting the distinction right is a key to success.

为了这些用户，也为了我们自己的产品，把这一区分做对是通往成功的一把钥匙。

Explanation and reference both belong to the theory half of the Diátaxis map - they don’t contain steps to guide the reader, they contain theoretical knowledge.

阐释（explanation）和参考（reference）都属于 Diátaxis 地图（map）中理论的那一半——它们不包含引导读者的步骤，而是包含理论知识（theoretical knowledge）。

The difference between them is - just as in the difference between tutorials and how-to guides - the difference between the acquisition of skill and knowledge, and its application.

它们之间的差别——正如教程（tutorial）与操作指南（how-to guide）之间的差别一样——是技能与知识的习得（acquisition）与其应用（application）之间的差别。

In other words it’s the distinction between study and work.

换句话说，就是学习（study）与工作（work）之间的区分。

Mostly it’s fairly straightforward to recognise whether you’re dealing with one or the other.

大多数时候，要辨认你面对的是哪一种，是相当直截了当的。

Reference, as a form of writing, is well understood; it’s used in distinctions we make about writing from an early age.

参考作为一种写作形式，是被人充分理解的；我们从小对写作所做的区分中，就用到了它。

In addition, examples of writing are themselves often clearly one or the other.

此外，写作的实例本身往往清楚地属于其中一种。

A tidal chart, with its tables of figures, is clearly reference material.

一张潮汐表，连同它的数字表格，显然是参考材料。

An article that explains why there are tides and how they behave is self-evidently explanation.

一篇解释为什么会有潮汐、潮汐如何运作的文章，则不言自明地是阐释。

There are good rules of thumb:

有一些好用的经验法则：

Imagine asking a friend, while out for a walk or over a drink, Can you tell me more about <topic>? - the answer or discussion that follows is most likely going to be an explanation of it.

想象一下，在散步途中或小酌时问朋友：你能多给我讲讲〈某话题〉吗？——随之而来的回答或讨论，很可能就是对它的一次阐释。

Mostly we can rely safely on intuition to manage the distinction between reference and explanations.

大多数时候，我们可以放心地依靠直觉来把握参考与阐释之间的区分。

But only mostly - because it’s also quite easy to slip between one form and the other.

但也仅仅是大多数时候——因为从一种形式滑入另一种形式，同样相当容易。

It usually happens while writing reference material that starts to become expansive.

这通常发生在撰写参考材料而它开始铺展开来的时候。

For example, it’s perfectly reasonable to include illustrative examples in reference (just as an encyclopaedia might contain illustrations) - but examples are fun things to develop, and it can be tempting to develop them into explanation (using them to say why, or show what if, or how it came to be).

例如，在参考中收入起说明作用的示例是完全合理的（就像百科全书里可以有插图一样）——但示例是很有意思、让人想展开的东西，人们很容易忍不住把它们发展成阐释（用它们来说为什么，或者展示假如会怎样，或者事情是如何演变至此的）。

As a result one often finds explanatory material sprinkled into reference.

结果，我们常常发现阐释性的材料被零星撒进了参考之中。

This is bad for the reference, interrupted and obscured by digressions.

这对参考不利——它被离题的枝节打断和遮蔽。

But it’s bad for the explanation too, because it’s not allowed to develop appropriately and do its own work.

但这对阐释同样不利，因为它没有得到充分展开、做好自己分内之事的机会。

The real test, though, if we’re in doubt about whether something is supposed to be reference or explanation is: is this something someone would turn to while working, that is, while actually getting something done, executing a task?

不过，当我们拿不准某样东西该算参考还是阐释时，真正的检验标准是：这是不是某人在工作时——也就是在实际做事、执行任务时——会去查阅的东西？

Or is it something they’d need once they have stepped away from the work, and want to think about it?

还是说，这是他们从工作中抽身之后、想对其进行思考时才需要的东西？

These are two very fundamentally different needs of the reader, that reflect how, at that moment, the reader stands in relation to the craft in question, in a relationship of work or study.

这是读者两种极为根本不同的需求（needs），反映出在那一刻，读者与所涉技艺（craft）处于何种关系之中——是工作的关系，还是学习的关系。

To help avoid being misled by intuition, see The compass.

要避免被直觉误导，请参见罗盘（the compass）。

Reference is what a user needs in order help apply knowledge and skill, while they are working.

参考是用户（user）在工作时，为帮助应用知识与技能而需要的东西。

Explanation is what someone will turn to to help them acquire knowledge and skill - “study”.

阐释是人们为帮助自己习得知识与技能而求助的东西——即"学习"。

Understanding those two relationships and responding to the needs in them is the key to creating effective reference and explanation.

理解这两种关系，并回应其中的需求，是创作出有效的参考与阐释的关键。

The application of Diátaxis to most documentation is fairly straightforward.

把 Diátaxis 应用到大多数文档（documentation）上是相当直截了当的。

The product that defines the domain of concern has clear boundaries, and it’s possible to come up with an arrangement of documentation contents that looks - for example - like this:

界定关注领域的那个产品有着清晰的边界，因此可以设计出一套文档内容的编排，看起来——举例来说——像这样：

In each case, a landing page contains an overview of the contents within.

在每种情况下，落地页（landing page）都包含对其内部内容的概览。

The tutorial for example describes what the tutorial has to offer, providing context for it.

比如教程（tutorial）的落地页会描述教程能提供什么，为它提供背景。

Even very large documentation sets can use this effectively, though after a while some grouping of content within sections might be wise.

即使是非常庞大的文档集也能有效地使用这种结构，不过到了一定规模，在各版块内部对内容做些分组也许是明智的。

This can be done by adding another layer of hierarchy - for example to be able to address different installation options separately:

这可以通过再增加一层层级来实现——例如为了能够分别处理不同的安装方式：

Contents pages - typically a home page and any landing pages - provide an overview of the material they encompass.

目录页——通常是首页和各个落地页——提供其所涵盖材料的概览。

There is an art to creating a good contents page.

做出一个好的目录页是一门艺术。

The experience they give the users deserves careful consideration.

它们带给用户（user）的体验值得仔细斟酌。

Lists longer than a few items are very hard for humans to read, unless they have an inherent mechanical order - numerical, or alphabetical.

超过寥寥数项的列表对人类来说非常难读，除非它们有一种内在的机械顺序——按数字排或按字母排。

Seven items seems to be a comfortable general limit.

七项似乎是一个让人舒适的普遍上限。

If you find that you’re looking at lists longer than that in your tables of contents, you probably need to find a way to break them up into small ones.

如果你发现自己的目录里出现了比这更长的列表，你多半需要想办法把它们拆成小的。

As always, what matters most is the experience of the reader.

一如既往，最重要的是读者的体验。

Diátaxis works because it fits user needs well - if your execution of Diátaxis leads you to formats that seem uncomfortable or ugly, then you need to use it differently.

Diátaxis 之所以有效，是因为它很好地契合了用户需求（needs）——如果你对 Diátaxis 的执行把你引向了让人别扭或难看的形式，那你就需要换一种用法。

The content of a landing page itself should read like an overview.

落地页自身的内容读起来就应该像一篇概览。

That is, it should not simply present lists of other content, it should introduce them.

也就是说，它不应只是罗列其他内容的清单，而应对它们做出引介。

Remember that you are always authoring for a human user, not fulfilling the demands of a scheme.

记住，你始终是在为一个活生生的用户写作，而不是在满足某个方案的要求。

Headings and snippets of introductory text catch the eye and provide context; for example, a how-to landing page:

标题和小段的引言文字能抓住眼球并提供上下文；例如，一个操作指南（how-to guide）的落地页：

A more difficult problem is when the structure outlined by Diátaxis meets another structure - often, a structure of topic areas within the documentation, or when documentation encounters very different user-types.

一个更棘手的问题，是 Diátaxis 勾勒的结构撞上另一种结构——常见的是文档内部的主题领域结构，或者文档要面对差异极大的用户类型。

For example we might have a product that is used on land, sea and air, and though the same product, is used quite differently in each case.

举个例子，我们可能有一个在陆、海、空都被使用的产品，虽然是同一个产品，但在每种场景下的用法大不相同。

And it could be that a user who uses it on land is very unlikely to use it at sea.

而且，在陆地上用它的用户很可能根本不会在海上用它。

Or, the product documentation addresses the needs of:

又或者，产品文档要满足以下几类人的需求：

The same product, but very different concerns.

同一个产品，关切却截然不同。

A final example: a product that can be deployed on different public clouds, with each public cloud presenting quite different workflows, commands, APIs, GUIs, constraints and so on.

最后一个例子：一个可以部署到不同公有云上的产品，每个公有云呈现的工作流、命令、API、图形界面、限制条件等都相当不同。

Even though it’s the same product, as far as the users in each case are concerned, what they need to know and do is very different - what they need is documentation not for product, but

虽然是同一个产品，但对各个场景里的用户来说，他们需要了解和操作的东西非常不同——他们需要的不是「产品」的文档，而是

So, we could decide on an overall structure that does this:

于是，我们可以选定这样一种整体结构：

or maybe instead this:

或者，也可以换成这样：

Which is better? There seems to be a lot of repetition in either cases.

哪种更好？两种方案里似乎都有大量重复。

What about the material that can be shared between land, sea and air?

那些可以在陆、海、空之间共享的材料又该怎么办？

Firstly, the problem is in no way limited to Diátaxis - there would be the difficulty of managing documentation in any case.

首先，这个问题绝不是 Diátaxis 独有的——无论如何，管理文档的困难都会存在。

However, Diátaxis certainly helps reveal the problem, as it does in many cases.

不过，Diátaxis 确实有助于把问题暴露出来，正如它在许多情况下所做的那样。

It brings it into focus and demands that it be addressed.

它让问题进入焦点，并要求你去解决它。

Secondly, the question highlights a common misunderstanding.

其次，这个疑问凸显了一个常见的误解。

Diátaxis is not a scheme into which documentation must be placed - four boxes.

Diátaxis 不是一个必须把文档塞进去的方案——不是四个盒子。

It posits four different kinds of documentation, around which documentation should be structured, but this does not mean that there must be simply four divisions of documentation in the hierarchy, one for each of those categories.

它提出了四种不同类型的文档，文档应当围绕它们来组织结构，但这并不意味着层级里必须恰好只有四个文档分区、每个类别各占一个。

Diátaxis can be neatly represented in a diagram - but it is not the same as that diagram.

Diátaxis 可以用一张示意图简洁地表示——但它并不等同于那张图。

It should be understood as an approach, a way of working with documentation, that identifies four different needs and uses them to author and structure documentation effectively.

它应当被理解为一种方法、一种处理文档的工作方式：识别出四种不同的需求，并利用它们来有效地撰写和组织文档。

This will tend towards a clear, explicit, structural division into the four categories - but that is a typical outcome of the good practice, not its end.

这往往会趋向于清晰、明确地按四个类别划分结构——但那是良好实践的典型结果，而不是它的目的。

Diátaxis is underpinned by attention to user needs, and once again it’s that concern that must direct us.

Diátaxis 的根基是对用户需求的关注，而这一次，仍然是这份关切必须为我们指引方向。

What we must document is the product as it is for the user, the product as it is in their hands and minds.

我们必须记录的是「对用户而言的产品」，是在他们手中、在他们心目中的那个产品。

(Sadly for the creators of products, how they conceive them is much less relevant.)

（对产品的创造者来说很遗憾：他们自己如何构想产品，远没有那么重要。）

Is the product on land, sea and air effectively three different products, perhaps for three different users?

陆、海、空的这个产品，实际上是不是三个不同的产品，或许面向三种不同的用户？

In that case, let that be the starting point for thinking about it.

如果是这样，就让这一点成为思考的起点。

If the documentation needs to meet the needs of users, developers and contributors, how do they see the product?

如果文档要同时满足用户、开发者和贡献者的需求，那么在他们各自眼中，产品是什么样的？

Should we assume that a developer who incorporates it into other products will typically need a good understanding of how it’s used, and that a contributor needs to know what a developer knows too?

我们是否应该假定：把它整合进其他产品的开发者，通常需要先充分理解它的用法；而贡献者又需要掌握开发者所知道的一切？

Then perhaps it makes sense to be freer with the structure, in some parts (say, the tutorial) allowing the developer-facing content to follow on from the user-facing material, while completely separating the contributors’ how-to guides from both.

那么，或许更自由地处理结构才是合理的：在某些部分（比如教程），让面向开发者的内容紧接在面向用户的材料之后；同时把贡献者的操作指南与这两者完全分开。

And so on. If the structure is not the simple, uncomplicated structure we began with, that’s not a problem - as long as there is arrangement according to Diátaxis principles, that documentation does not muddle up its different forms and purposes.

依此类推。如果最终的结构不再是我们开头那个简单、不复杂的结构，那也不成问题——只要确实存在依照 Diátaxis 原则的编排，只要文档没有把它不同的形式和目的搅混在一起。

Documentation should be as complex as it needs to be.

文档应当具备它所需要的复杂度。

It will sometimes have complex structures.

它有时就是会有复杂的结构。

But, even complex structures can be made straightforward to navigate as long as they are logical and incorporate patterns that fit the needs of users.

但是，即便是复杂的结构，只要它合乎逻辑，并且融入了契合用户需求的模式，也可以让人一目了然地穿行其间。

Diátaxis is the work of Daniele Procida.

Diátaxis 是 Daniele Procida 的作品。

It has been developed over a number of years, and continues to be elaborated and explored.

它历经多年发展而来，至今仍在继续深化与探索之中。

Email me. I enjoy hearing about other people’s experiences with Diátaxis and read everything I receive.

给我发邮件吧。我很乐意听到其他人使用 Diátaxis 的经历，收到的每一封来信我都会读。

I appreciate all the interest and do my best to reply, but I get a considerable quantity of email related to Diátaxis and I can’t promise to respond to every message.

我感激大家的关注，也会尽力回复，但与 Diátaxis 相关的邮件数量相当可观，我无法保证每封都能回复。

If you’d like to discuss Diátaxis with other users, please see the #diataxis channel on the Write the Docs Slack group, or the Discussions section of the GitHub repository for this website.

如果你想和其他用户讨论 Diátaxis，请前往 Write the Docs Slack 群组的 #diataxis 频道，或本网站 GitHub 仓库的 Discussions（讨论）区。

You can find an earlier presentation of some of these ideas, that I created while working at Divio between 2014-2021.

你可以找到这些想法中一部分的早期呈现，那是我 2014 至 2021 年间在 Divio 工作时创作的。

I still agree with most of it, though there are several aspects that I now think I got wrong.

其中大部分内容我至今仍然认同，不过有几个方面，我现在认为当时是搞错了。

The original context for the Diátaxis approach was limited to software product documentation.

Diátaxis 方法最初的应用语境仅限于软件产品文档（documentation）。

In 2021 I was awarded a Fellowship of the Software Sustainability Institute, to explore its application in scientific research contexts.

2021 年，我获得了软件可持续性研究所（Software Sustainability Institute）的研究员资助，用于探索它在科学研究场景中的应用。

More recently I’ve explored its application in internal corporate documentation, organisational management and education, and also its application at scale. This work is on-going.

最近我还探索了它在企业内部文档、组织管理与教育中的应用，以及它在大规模场景下的应用。这项工作仍在进行中。

Other people have corresponded with me to share their experience of applying Diátaxis to note-taking systems and even as part of a systematic approach to household management.

还有一些人来信与我分享他们的经验：把 Diátaxis 应用于笔记系统，甚至把它用作系统化家务管理方法的一部分。

To cite Diátaxis, please refer to this website, diataxis.fr.

如需引用 Diátaxis，请引用本网站 diataxis.fr。

The Git repository for the source material contains a citation file, CITATION.cff.

源材料的 Git 仓库中包含一个引用文件 CITATION.cff。

APA and BibTeX metadata are available from the Cite this repository option at https://github.com/evildmp/diataxis-documentation-framework.

APA 与 BibTeX 格式的元数据可通过 https://github.com/evildmp/diataxis-documentation-framework 页面上的 Cite this repository（引用此仓库）选项获取。

You can also submit a pull request to suggest an improvement or correction, or file an issue.

你也可以提交 pull request 来建议改进或更正，或者提交 issue。

Diátaxis is now used in several hundred projects and it is no longer possible for me to keep up with requests to have projects listed here as examples of Diátaxis adoption.

Diátaxis 如今已被数百个项目采用，要求把项目列在这里作为 Diátaxis 采用示例的请求，我已经无力一一处理了。

This website is built with Sphinx and hosted on Read the Docs, using a modified version of Pradyun Gedam’s Furo theme.

本网站使用 Sphinx 构建，托管在 Read the Docs 上，采用了 Pradyun Gedam 的 Furo 主题的修改版。

If you'd like to help translate Diátaxis into your language, that would be very welcome.

如果你愿意帮忙把 Diátaxis 翻译成你的语言，非常欢迎。

The best way to contribute to translation is to join the project on Transifex.

参与翻译最好的途径是在 Transifex 上加入本项目。

Transifex is set up for translation into French, Portuguese (Brazil), German, Korean, Chinese (Simplified) and Spanish. Other languages can be set up on request by emailing me.

Transifex 上已开通法语、巴西葡萄牙语、德语、韩语、简体中文与西班牙语的翻译；其他语言可发邮件向作者申请开通。

As soon as a translation is complete, I will publish it on https://diataxis.fr. There's a staging version of this site with translations.

译本一旦完成，作者就会发布在 https://diataxis.fr 上；站点另有一个带译文的预览（staging）版本。

Translation contributions are accepted under the Creative Commons Attribution-ShareAlike 4.0 International Public License.

翻译贡献按「知识共享 署名-相同方式共享 4.0 国际」（CC BY-SA 4.0）许可接受。