Vue 3.0文档编写指南#原则

vicky.yu

#原则
除非有充分的文档证明，否则功能不存在。
尊重用户的认知能力 (即脑力)。当用户开始阅读时，他们从一定量的有限脑力开始，而当他们用完时，他们停止学习。
复杂的句子、一次必须学习一个以上的概念，以及与用户的工作没有直接关系的抽象例子，认知能力消耗得更快。
当我们帮助他们持续感到聪明、强大和好奇时，他们的认知能力会慢慢消耗殆尽。把事情分解成可消化的部分并注意文档的流动可以帮助它们保持这种状态。
总是试着从用户的角度看问题。当我们彻底理解某件事情时，它就变得显而易见了。这就是所谓的知识诅咒。为了编写好的文档，记住在学习这个概念时首先需要知道什么。你需要学什么行话？你误解了什么？什么花了很长时间才真正掌握？好的文档可以满足用户的需求。这可能有助于练习向人们解释这个概念
首先描述*问题*，然后描述解决方案。在展示功能如何工作之前，解释其存在的原因非常重要。否则，用户将无法知道这些信息对他们是否重要 (这是他们遇到的问题吗？) 或与之前的知识/经验相联系。
在写作时，不要害怕问问题，尤其是如果你害怕他们“蠢”的话。脆弱是很难的，但这是我们更充分地理解我们需要解释的唯一途径。
参与特性讨论。最好的 API 来自于文档驱动的开发，我们在开发中构建易于解释的特性，而不是试图在以后解释它们。提前提出问题 (尤其是“愚蠢的”问题) 通常有助于揭示困惑、不一致和有问题的行为，然后才需要进行破坏性的更改来修复它们。