文档加粗更粗
One of the hardest things about writing documentation as a developer is to step into the shoes of the user. When you know everything about a feature of a product, it can be extraordinarily hard to see the whole thing with fresh eyes. We went through that exercise recently with NavMesh, and I wanted to share you how we did it.
作为开发人员编写文档的最困难的事情之一就是步入用户的视野。 当您了解有关产品功能的所有信息时，很难用新鲜的眼睛看清整个产品。 我们最近与NavMesh一起完成了该练习，我想与您分享我们的工作方式。
实施模型与心理模型 (Implementation Model vs. Mental Model)
One way to be able to dive into the users perspective is to inspect the product from the implementation model and mental model. Simplified, implementation model is the way the developer sees the product, and mental model is how the users sees things. These can be very different.
能够深入用户视角的一种方法是从实施模型和思维模型检查产品。 简化的实现模型是开发人员查看产品的方式，思维模型是用户查看事物的方式。 这些可以有很大的不同。
For example the implementation model of a car is all about cylinders, spark plugs and differential gears, but the mental model is a vehicle which gets you around. The more advanced you are in a topic, the more you eventually learn about the implementation model too. But the common case is that you wish that it would just work.
例如，汽车的实现模型全部与气缸，火花塞和差速器有关，而思维模型则是使您转身的汽车。 您在主题中越高级，最终对实现模型的了解也就越多。 但是常见的情况是您希望它能正常工作。
Here’s the journey that most Unity users go through when learning a new feature:
这是大多数Unity用户学习新功能时要经历的过程：
-
Fundamentals describe what the whole feature is all about and how it’s different pieces fit together. If you have some problem you’d like to solve, the fundamentals should give you just enough information that you can start solving the problem.
基本原理描述了整个功能的全部内容以及不同部分如何组合在一起。 如果您有想要解决的问题，那么基本原理应该为您提供足够的信息，您可以开始解决问题。
-
Procedures map the fundamentals into things and workflows in the Unity UI, such as adding specific components or baking NavMeshes.
过程将基础知识映射到Unity UI中的事物和工作流程中，例如添加特定的组件或烘焙NavMeshes。
-
Techniques combine all of the above to solve actual problems, for example: how to move a game character to the point you clicked on your level?
技巧结合了以上所有内容来解决实际问题，例如：如何将游戏角色移动到您在关卡上单击的位置？
Before the user gets into the fundamentals she’s often faced with some sort of communication about the feature. For example a novice user might not even know that he should be looking for NavMesh in the first place, or more advanced use might just skim around to see if the specific feature she’s looking for is covered. This is often covered by our marketing material, blog posts, forums and Unity evangelists.
在用户了解基础知识之前，她经常会遇到有关该功能的某种交流。 例如，新手用户甚至可能根本不知道自己应该在寻找NavMesh，或者更高级的使用可能只是在附近浏览以查看是否覆盖了他所寻找的特定功能。 我们的营销材料，博客文章，论坛和Unity宣传人员经常对此进行介绍。
Many of our users of not ever reach the very deepest end of the pool, but some do. When you want to optimise the last bits of your game, or if you have very specific need, you may end up reaching the point where you’re poking right at the implementation model.
我们的许多用户从未达到过池中最深的一端，但有些用户却达到了。 当您想优化游戏的最后部分时，或者如果您有非常特定的需求，您可能最终会碰到正确的实现模型。
To sum up, the first step was to understand what types of information the users need when they learn a new Unity feature. The next step is to understand who to write to.
总而言之，第一步是了解用户在学习新的Unity功能时需要哪些类型的信息。 下一步是了解给谁写信。
了解你的观众 (Know Your Audience)
The need to write better documentation emerged from a discussion we had earlier this year about the audience for Unity NavMesh. We talked to people and tried to tease out what was missing and what their pain-points were.
我们今年早些时候对Unity NavMesh的受众进行了讨论，从而产生了编写更好文档的需求。 我们与人们交谈，并试图弄清缺少的东西以及他们的痛点。
Based on the interviews and previous discussions with our users, we build a number of personas (or characters). These personas provide a way to walk down from mental model towards the implementation model with a specific state of mind. The journey will be different for a novice versus a pro users and differs based on discipline too.
根据与用户的访谈和先前的讨论，我们建立了许多角色 (或角色)。 这些角色提供了一种从思维模型转到具有特定思维状态的实现模型的方法。 无论是新手还是专业用户，旅程都会有所不同，并且基于纪律也有所不同。
We mapped 5 personas, here’s who they are:
我们绘制了5个角色，这是他们：
-
Fernandez, Hobbyist game developer, “I’m new and I just want to make a mobile game.”
业余游戏开发商 Fernandez ，“我是新手，我只想制作一款手机游戏。”
-
Ivo, Senior game programmer gone Indie, “I’m veteran programmer, implementing AI for the first time.”
高级游戏程序员 Ivo 离开了Indie ，“我是资深程序员，是第一次实现AI。”
-
Oleg, Senior AI Programmer, “I’m reimplementing our old AI system in Unity.”
高级AI程序员 Oleg： “我正在Unity中重新实现旧的AI系统。”
-
Laurent, Senior Game/Level Designer, “I want to design complex game with great AI”
Laurent ， 高级游戏/关卡设计师 ，“我想用出色的AI设计复杂的游戏”
-
Miia, Architect, “I want to add life to my architecture visualization”
Miia ， 建筑师 ，“我想为我的建筑可视化增添生命”
We further organized them based on “how much AI” they want, and “how much programming” they can do. The idea was to try to find outliers, such as Laurent, who will require more tools to be efficient in his job.
我们根据他们想要的“多少AI”和他们可以进行的“多少编程”来进一步组织它们。 这个想法是试图找到离群的人，例如洛朗(Laurent)，他们将需要更多的工具来提高工作效率。
One part of the process is to also pick which personas to focus on. We chose to focus on Ivo, since the things we needed to improve for him, also helped Fernandez and Oleg. For the time being we’re focusing on programming savvy users, leaving out, but not forgetting, Laurent and Miia.
该过程的一部分是还选择要关注的角色。 我们选择专注于Ivo，因为我们需要为他改进的事情也帮助了Fernandez和Oleg。 暂时，我们专注于为精明的用户编程，而不是忘记Laurent和Miia，但不能忘记。
Personas change over time, we reconsider the validity of the list after each release as we learn more about our users and their projects. In addition just writing documentation, personas are a great way to focus work too.
角色随着时间而变化，随着我们更多地了解用户及其项目，我们将在每个发行版之后重新考虑列表的有效性。 除了编写文档外，角色也是一种集中工作的好方法。
文档驱动开发 (Documentation Driven Development)
Now that we know what we need to explain and to whom, the task of changing perspective and explain things becomes a lot easier.
既然我们知道了我们需要向谁解释的内容，那么改变观点和向他人解释的任务就变得容易得多。
One thing we found sorely missing was the fundamentals, so we started with that. One thing lead to another, and soon we had procedures and some common techniques explained too.
我们发现根本缺少的一件事是基础知识，因此我们从这一点开始。 一件事导致另一件事，很快我们就获得了程序和一些常用技术的解释。
At times trying to explain things in plain (Nordic) English was quite humbling. Some features looked really simple from the implementation point of view, but felt upside down, when trying to explain them from user’s point of view.
有时试图用简单的(北欧的)英语来解释事情是很谦卑的。 从实现的角度来看，某些功能看起来确实很简单，但是当尝试从用户的角度来解释它们时却有些倒置。
More often than not, if something takes a lot of effort to explain, it is often also hard to understand. That does not mean that you cannot explain complex things. Being able to refer to existing documentation, such as the fundamentals, can greatly simplify the explanation.
通常，如果需要花很多精力来解释，通常也很难理解。 这并不意味着您无法解释复杂的事物。 能够参考现有文档(例如基础知识)可以大大简化说明。
One thing we want try later is to “improvise” the documentation earlier in the development process as a first test to see if the UI and the terms make sense when talked out loud. I guess one could almost call that documentation driven development.
我们想要稍后尝试的一件事是在开发过程的早期“完善”文档，作为第一个测试，以查看大声说出UI和术语是否有意义。 我猜几乎可以说是文档驱动的开发。
Here’s a programmer literature version of the doc we wrote. From here our great doc team will take over and turn that into a proper documentation.
这是我们编写的文档的程序员文献版本。 从这里，我们强大的文档团队将接管并将其变成适当的文档。
We found this first pass very useful, but we want to improve going forward. For example we want to learn how to present more advanced techniques concisely, how to write better API docs so that they answer the question you had in mind when looking things up, and how to better APIs and components in the first place so that they are easier to explain.
我们发现此第一遍非常有用，但是我们希望继续改进。 例如，我们想学习如何简洁地介绍更高级的技术，如何编写更好的API文档，以便他们回答您在查找内容时遇到的问题，以及如何首先改善API和组件，以便他们更容易解释。
Stumbling towards better documentation,
试图获得更好的文档，
– The AI team.
– AI团队。
翻译自: https://blogs.unity3d.com/2014/07/01/building-better-documentation/
文档加粗更粗