#风格
标题应该描述问题，不是解决方案。例如，一个不太有效的标题可能是“使用 prop”，因为它描述了一个解决方案。一个更好的标题可能是“通过 Props 将数据传递给子组件”，因为它提供了 Props 解决问题的上下文。用户不会真正开始注意某个功能的解释，直到他们知道为什么/何时使用它。
当你假设知识时，就要声明它，在开始时，链接到参考资料，以获得你期望的不太常见的知识。
尽可能一次只引入一个新概念 (包括文本和代码示例)，即使当你介绍不止一个的时候很多人都能理解，也有很多人会迷失方向，即使那些没有迷失方向的人也会耗尽更多的认知能力。
尽可能避免使用特殊的内容块来获取提示和注意事项，一般来说，最好将这些内容更自然地融合到主要内容中，例如，通过构建示例来演示边缘案例。
每页不要超过两个相互交织的提示和注意事项，如果你发现一个页面需要两个以上的提示，请考虑添加一个警告部分来解决这些问题。本指南的目的是通读，提示和注意事项可能会让试图理解基本概念的人不知所措或分心。
避免诉诸权威 (例如，“你应该做 X，因为这是一个最佳实践”或“X 是最好的，因为它能让你完全分离关注点”)。相反，用例子来演示由模式引起和/或解决的具体人类问题。
当决定先教什么时，想想哪些知识能提供最好的动力/努力比。这意味着教任何能帮助用户解决最大痛苦或最大数量问题的东西，而学习的努力相对较少。这有助于学习者感到聪明、强大和好奇，因此他们的认知能力会慢慢流失。
除非上下文采用字符串模板或构建系统，否则只能编写在软件的任何环境中工作的代码 (例如 Vue、Vuex 等)
显示，不要说例如，“要在页面上使用 Vue，可以将其添加到 HTML 中”(然后显示脚本标记)，而不是“要在页面上使用 Vue，可以添加一个具有 src 属性的脚本元素，该属性的值应为指向 Vue 编译源的链接”。
几乎总是避免幽默 (对于英文文档)， 尤其是讽刺和通俗文化的引用，因为它在不同文化之间的翻译并不好。
永远不要假设比你必须的更高阶的上下文。
在大多数情况下，比起在多个部分中重复相同的内容，更喜欢在文档的各个部分之间建立链接。在内容上有些重复是不可避免的，甚至是学习的必要条件。然而，过多的重复也会使文档更难维护，因为 API 的更改将需要在许多地方进行更改，而且很容易遗漏某些内容。这是一个很难达到的平衡。
具体的比一般的好例如，一个 <BlogPost> 组件例子比 <ComponentA> 更好。
相对胜于晦涩。例如，一个 <BlogPost> 组件例子比 <CurrencyExchangeSettings> 更好。
保持情感相关。与人们有经验并关心的事物相关的解释和示例将永远更加有效。
始终喜欢使用简单，简单的语言，而不是复杂或专业的语言。例如：
“你可以将 Vue 与脚本元素一起使用”，而不是“为了启动 Vue 的使用，一种可能的选择是通过脚本 HTML 元素实际注入它”
“返回函数的函数”而不是“高阶函数”
避免使用毫无意义的语言。如“简单”、“公正”、“明显”等，请参阅教育写作中应避免的词语。
#语法
避免缩写在编写代码和示例代码中 (例如，attribute 优于 attr，message 优于 msg)，除非你在 API 中明确引用了缩写 (例如 $attrs)。标准键盘上包含的缩写符号 (例如，@，#，&) 可以。
当引用直接下面的示例时，请使用冒号 ( 结束句子，而不是句点 (.)
使用牛津逗号 (；例如：“a，b，and c”替换“a，b and c”)。！为什么牛津逗号很重要
来源：The Serial (Oxford) Comma：When and Why To Use It
引用项目名称时，请使用项目引用自身的名称。例如，“webpack”和“npm”都应使用小写字母，因为这是它们的文档引用它们的方式。
使用标题大小写作为标题 - 至少到目前为止，因为这是我们在其余文档中使用的。有研究表明，句子大小写 (仅标题的第一个单词以大写字母开头) 实际上在可读性上是优越的，并且还减少了文档作者的认知开销，因为他们不必记住是否要大写“and”，“with”和“about”。
请勿使用表情符号 (讨论中除外)。Emoji 既可爱又友好，但是它们可能会使文档分散注意力，有些表情符号甚至会在不同文化中传达不同的含义。 |
发表于 2024-1-2 09:35
|