# 同源开发方法论 事实上同源开发不用完全拘泥于前文提到的细节技巧。如本文开头就已经多次强调的，技术文档写作是一项工程，它的具体实现是灵活的、取决于工程师的构建。而同源开发是一套方法论、一套指导思想。因此，相比具体的细节技巧，本篇中的方法论和原则才是现代化的技术文档写作的真正核心。 下文主要介绍了同源开发的五大基本开发原则。基于技术文档写作与其他工程学科的共性，这些原则有不少来源于其他学科领域。因此，如果读者看到了自己涉及领域所熟悉的内容，不必太过惊讶，毕竟优秀的构建思想都是相通的。 ## 干货原则（The Dry Principle） **DRY**代表的是 "不要重复自己"。而这可以说是最基本，同时也是最重要的原则。 **Single Sourcing**的理念就是，每次 "重复自己 "的时候，你应该开始思考，你可能做错了什么。 所以，你要做的是，不要在多个地方重复同一个内容，而是要思考：有没有什么办法可以代替我重复使用这个内容？ 只要你理解了“同源”的基本概念，这听起来好像是理所当然的! 但事实是，你需要一些时间来习惯总是寻找重用内容的过程。而这个原则的好处并不是真的要增加一些新的复杂的东西，恰恰相反，它通过如此直接简单的措辞，帮助你时刻牢记同源开发的这个基础。 所以，如果你在任何时刻发现自己在想 "我以前写过这样的东西"，这应该会触发**Don't Repeat Yourself**原则--然后绞尽脑汁想办法重用，而不是重写! ## KISS原则（The KISS principle） **KISS**原则代表着 **"Keep It Simple, Stupid"**，或者用稍加修饰的解释，**"Keep It Simple and Straightforward"**。 在编程中，这指的是总是有很多方法来完成功能，但最简单的方法通常是最好的。(稍微延伸一下，你可以认为奥卡姆剃刀也是类似的原则)。 同源开发也是一样的，你作为一个技术写手，也会像程序员一样有很多工具可以使用。而这个原则的想法是确保你明智地使用这些工具。 你可以使用这些工具，并不意味着你应该使用全部的这些工具。 把这个原则看成是**DRY**原则的一个平衡点是个好主意--也就是说，尽量找到巧妙的方法来重复使用内容，但不要过度到让你的内容变得太复杂的地步。 所以，如果你发现自己有很多选择来架构你的内容，实现复用，而其中一个真的很复杂--实现完美的复用，而另一个比较简单，实现了一些复用，但不是100%，那么选择很可能是后者。在选择用什么策略来创建你的内容时，如果收益不值得，就选择更简单的方案吧! 因为你要考虑的是，无论你的复用方案多么巧妙，你都要保证别人能理解你的做法，也要保证以后的维护。 当你掌握了前面的原则（**DRY**），你很快就会进入猎取重用的思维模式。这是好的。但**KISS**原则就会有助于平衡这一点。甚至可以说是 "杀死你的宝贝"，帮助你考虑重用不值得的情况。你可能会看到重用的可能性，但如果实现它所需要的技术使文档难以维护，那么最好完全放弃这个特定的重用机会。 ## 知识最少原则（只和朋友说话） 再回到编程的类比，这与一个事实有关，即如果你在编程函数之间建立了大量的依赖关系，这些函数将无法重用。 同样的事情也适用于基于主题的编写和技术写作中的重用。 你的目标应该是让你的主题 “独立”，例如，在你的内容块之间创建“依赖”时要小心。更具体地说，一个例子可能是不要不必要地在主题之间建立链接。 一旦你在主题之间创建了一个链接（例如交叉引用），你就有可能创建了一个依赖关系。这意味着，如果你想在任何出版物中使用该主题，你需要确保它所链接的主题也被包含在内。而当你考虑到你的目标应该是让主题在许多不同的上下文中可以重复使用（例如多个产品的文档），那么你就不能理所当然地认为你在一个出版环境中链接到的目标主题实际上会出现在另一个出版环境中。 这个原则的另一个名字也许更有帮助。"只和你的朋友说话"--即在这种情况下，只有在你知道他们是亲密的 "朋友 "的情况下，才会链接或连接到其他主题。 在一组技术文档的主题中，“朋友”意味着什么？好吧，如果你知道一个主题和另一个主题总是需要在一起，那么可能就可以链接到它或者创建某种依赖关系。 当然，如果你有一个好的内容管理系统，它会帮助你解决很多这些事情。但总的来说，在创建依赖关系方面还是要有所限制。 ## 单一责任原则（The Single Responsibility Principle） 这个原则指的是，一个主题（或原始编程背景下的功能）只应该有一个责任，或“工作”。这意味着，它应该只完成一个目的/包含一个主题。例如，如果我写了一个主题，既描述了一个发动机的安全信息，又描述了如何安装它，我就给这个主题分配了两个责任。这种情况应该避免。 因为如果我这样做，如果关于发动机的安全信息实际上可以和其他一些发动机共享呢？如果我把两种信息类型混在一起，我就很难再利用了。 单一责任原则可以帮助我们将主题划分为更小的部分，确保内容更可重用。通过确保我们不试图同时执行两种功能（描述、指导等），我们使内容更容易重用。这也类似于软件设计架构中的“高内聚，低耦合”原则。 ## 抽象和概括原则（The Abstraction and Generalization Principle） 在这个原则的原始编程版本中，它的意思是，如果你有机会让一个函数变得通用而不是具体，就这样做。 在技术写作的语境中，同样的事情也适用：如果你有机会让一个主题更 "通用"，就这样做。基于主题的写作背后的整个想法是，你应该将你的内容分解成更小的内容块，然后重复使用它们。因此，你需要让你的主题尽可能地重复使用。如果你把它们做得很具体，它们就不会被重复使用。 例如，想象一下你正在写两个不同（但相似）的产品。它们有相同的描述、安全信息等。而唯一不同的是产品型号名称。 在这种情况下，这个原则说的是：如果你真的不需要提及产品型号名称，就不要这样做! 如果不能增加内容的可理解性，你为什么要这么做呢? 你所要达到的目的就是让这个话题变得不可重复使用。相反，如果你不写产品名称，而其他内容对两者来说是一样的，你就可以重复使用它! 当然，有些情况下，漏掉具体内容可能会降低文档的质量，那么你就不应该漏掉。有一些技术可以绕过这个问题，并且仍然坚持这个原则，比如使用变量。但在大多数内容可复用的情况下，省略产品型号名称等具体内容通常对读者来说根本没有任何区别。然后这就是最简单的解决方案（提示一下前文提到的**KISS**原则）。