category
单源发布是一项强大的必备功能，通常是任何专业帮助创作解决方案的三大竞争优势之一，这是有充分理由的。单一来源的可重复使用内容使您能够：
- 在整个文档中保持风格、术语、详细程度等方面的一致性。
- 避免在用户界面或工作流发生更改时进行多次更新。
- 减少审查和编辑工作量。
- 降低本地化成本。
- 自动化日常工作——重复复制相同的内容会增加日常工作，并重复您的工作。
虽然我们并不反对单源发布的好处，但在这篇文章中，我们想提醒您注意它的陷阱，以便您得到预警，并可以明智地重用内容。
在JetBrains，我们经常重复使用内容。如果您熟悉我们的IDE，您就会知道它们是建立在IntelliJ平台之上的，这意味着有很多共享内容在不同的过滤器和条件下进入多个文档实例。
这里有一个简化的方案，让您了解如何在不同的文档实例之间重用整篇文章和较小的内容块：
我们有21个在线帮助实例是从同一组源文件构建的，大约有20多名技术作者为这个项目做出了贡献，所以我们对单个源文件了如指掌，以前也曾陷入过它的每一个陷阱。
在这篇文章中，我们将看看其中的一些陷阱，我将其命名如下：
- 滥用重复使用
- 源代码缩减
- 重复使用的滥用
- 流量蚕食
1.滥用重复使用
具有单源功能的工具允许您在条件和筛选器下包含重复使用的内容，从而为您提供了很大的灵活性。有时候灵活性太大了，真的。
让我们看一个内容重用的例子，其中包含了过滤器是合理的条件。这里使用过滤器是因为编程语言有不同的组件。例如，在Java中，您将搜索方法的用法，而在C++中，这将被称为函数，在数据库工具中，您可以搜索表、列或键的用法。
所以这里的过滤器是合法的。
<tip-of-the-day id="FindUsages"> <p> You can view the list of all usages of a <for product="ij,py,ws,ps,rm">method</for> <for product="cl">function</for> <for product="db">table, column, or key</for> across the whole project, and quickly navigate to the selected item. </p> </tip-of-the-day>
现在我们来看另一个例子：
<tip-of-the-day id="ChangeSorting" product="ij,py,ws"> <p product="ij"> You can sort completion suggestions by relevance or alphabetically. </p> <p product="py"> By default, completion suggestions are sorted by relevance, but you can sort them alphabetically bу selecting the <control>Sort by Name</control> option. </p> <p product="ws"> To choose how you want to sort completion suggestions - by name or relevance - toggle the <control>Sort by Name</control> checkbox. </p> </tip-of-the-day>
你能猜出这里出了什么问题吗？这里的三段内容完全相同。唯一不同的是措辞和细节水平。除了标题之外，实际上这里什么都没有重复使用。
🪴 根本原因
发生这样的事情有几个原因：
- 作家们认为他们可以想出比原作更好的措辞，但他们不愿意用自己的变体取代同行的作品。
- 作者会受到用户对细节水平不满意的反馈的影响，并添加多余的信息作为对反馈的反应。
⚖️ 权衡得失
你还记得为重复使用而烦恼的原因吗？让我们对照这个例子来衡量一下：
如何避免
以下是我们在作家团队中实施的一些策略，以帮助我们防止类似的事情发生：
- 我们开发了一个内部风格指南。在许多情况下，这有助于我们避免重复使用的滥用，因为在提供多少细节、语调等方面达成了一致，所以这些东西不是作家个人品味的问题。
- 我们已经根据我们的风格约定进行了自动检查，以便在编辑器中突出显示违反风格的行为，并提示作者重新措辞。根据您使用的编辑器，有不同的方法来实现此类检查。如果你使用的是JetBrains IDE，你可能想看看Grazie Professional插件，它支持Vale语法，并内置了一些流行的风格指南。
- 在我们的团队中，我们达成了“为自己改进——为每个人改进”的原则。你不需要害羞地为每个人改进一段文本，而不是将类似的块相乘。
- 我们还致力于实现一个语法检查器，该检查器可以检测非精确重复，并建议将它们提取到库中，以便重用。我们已经准备好使用这种linter的MVP，但我们也在研究不同的方法，这些方法可能涉及ElasticSearch、机器学习等技术。
2.源代码缩减
有时你想编辑一个页面并打开源文件，而你看到的只是几个屏幕长的网页后面的几行。你发现多个包含被包裹在一起，过滤器和变量被声明为天知道在哪里，你需要一段时间才能弄清楚你在网页上看到的文本实际上是什么。
以下是我最近在波特兰撰写文档会议上的演讲中的一个代码缩减示例：
🪴 根本原因
由于我们公司生产开发人员工具，我们作为作者与开发人员密切合作，为开发人员写作。我们通常倾向于采用开发人员的方法，甚至在IDE中编写文档。因此，我们有时会被源代码的美丽和简洁所折服，它被简化为一行代码，让你像嵌套的玩偶一样揭开它背后的内容层。
⚖️ 权衡得失
现在，让我们回顾一下我们的好处列表，并对照它们测试这个例子。
💡 如何避免
老实说，这不是我们JetBrains的冠军，但作为一个团队，你需要在重用所有可能重用的东西和保持代码可读性和可搜索性之间找到平衡。我们建议您尽量坚持以下原则：
- 仅仅因为你可以并不意味着你应该这样做。
- 有时，与其选择错误的抽象，不如选择一些重复，并忍受低于100%的重用。否则，您可能会创建僵化且难以维护和重用的源代码，从而使您的生活变得复杂。而你为减少它所做的投资永远无法收回。
3.重复使用的滥用
有时，你会意识到自己每周都会写几次相同的短语（比如设置页面的路径）。人们很自然地会想，如果你经常重复自己，你一定做错了什么，重复使用它是有意义的。
下面是一个告诉如何在IDE中配置某些内容的过程。
让我们看看第一步背后的源代码：
<include src="PREF_CHUNKS.xml" include-id="step_open_settings_page">
<var name="page_path"
value="Build, Execution, Deployment | %language% Profiler"/>
</include>
<chunk id="step_open_settings_page">
<step>
<include src="PREF_CHUNKS.hml" include-ide="open_settings_page"/>
</step>
</chunk>
<chunk id="open_settings_page">
Press <shortcut key="ShowSettings"/> to open the IDE settings and select
<control>%page_path%</control>.
</chunk>
要重用这里可能重用的所有内容，您需要引入变量并将可重用的代码段封装到另一个代码段中。所以，最后，在这个小句子后面有10行代码。我在问自己——这真的值得吗？
🪴 根本原因
在软件开发中，有一个原理叫做“DRY”。早在1999年，一本名为《务实的程序员》的书中就提出了这一观点。这里的“DRY”代表“Don't Repeat Yourself”，它旨在减少软件模式的重复，并用抽象来代替它，以避免冗余。
就像在编程中一样，这一原则经常被技术编写人员误解，他们试图重复使用任何可能重复使用的东西，并将多个可重复使用的片段包装在一起，从而创建复杂的标记结构，其中更改一个元素会破坏其他依赖元素的逻辑。
⚖️ 权衡得失
如何避免
我们能做些什么？
- 请记住，“DRY”原则并不总是有效的。如果你努力实现完美的重用，你最终可能会实现一个错综复杂的依赖球，你的队友很难理解和维护代码。
- 告诉告诉你，“DRY”原则的反义词是“WET原则，它代表“We Enjoy Typing”或“Write Every Time”，甚至“Waste Everyone’s Time”。然而，我建议相反的应该是20世纪60年代在美国海军引入的“KISS”原则，即“保持简单，愚蠢”。这表明，如果大多数系统保持简单而不是变得复杂，那么它们的工作效果最好。
- 想想其他方法来实现你的目标。在这个例子中，作者的最终目标是自动完成键入相同短语的常规任务。就像在编程语言中一样，通常有多种方法可以实现相同的目标。在这种情况下，您可以创建一个模板或一个完成模式，并为其分配一个热键组合，这样您就可以通过几次按键粘贴所需的文本。
这不是对每个人来说都更容易吗？
4.流量蚕食
在前面的四节中，我们讨论了如果内容作者不权衡内容重用的收益和可能的损失，他们可能会陷入困境。这一点影响到我们的客户——阅读技术文档的人。
当你把受众拉向多个方向时，网络内容就会被蚕食。
当您重用内容并将相同的内容块发布到网络上的多个输出时，就会发生这种情况。像谷歌这样的搜索引擎只是忽略了一些网页，因为相同的内容已经存在于不同的页面上，并且在搜索结果中排名更高。
这是一个搜索查询的例子。
排名第一的是关于多个光标的相关文章，只在JetBrains Rider（一种不同的JetBrains产品）中，而不是IntelliJ IDEA中。
本文的内容来源单一，出于某种原因，谷歌认为Rider文档中的页面更具相关性。
🪴 根本原因
我们的SEO专家帮助我们确定了这个问题的一些原因（尽管列表可能不完整）：
- 如果内容发布得更早，则索引也会更早。因此，如果JetBrains Rider在IntelliJ IDEA发布前几周发布，那么谷歌爬虫很可能在IntelliJ IDEA文档发布前就已经为本文编制了索引。
- 页面上的内容越少，索引就越好。有时，我们团队中的文档作者会重复使用一些零碎的东西，但整个部分的架构是不同的。这正是JetBrains Rider的情况——多个插入符号的信息被放在一个独立的帮助主题中，而在IntelliJ IDEA中，它是一篇更大文章中的一章，因此包含关键字的标题级别较低。
- SEO专家还告诉我们，更多的流量和来自其他来源的页面链接也会带来更好的排名，因此JetBrains Rider文档可能在其他文章中包含更多对该部分的引用。
💡 如何避免
SEO专家告诉我们，只有当你的内容是独一无二的，你才能避免流量被蚕食。既然我们已经了解了这种现象，我们应该完全停止重复使用内容吗？显然不是。单一来源内容的收益仍然很大。
所以我的第一条建议是要意识到这个问题。预先警告就是预先准备。只要记住，在网络上发布内容后，你的工作还没有完成。写得好的文档具有巨大的营销潜力，所以你总是需要尽你所能确保它有效、可发现和可访问，并在需要时采取行动。
当涉及到行动时，您可以执行以下操作：
- 如果您重用的是内容片段而不是整篇文章，则可以将包含更多关键字的元数据嵌入到源中，以帮助搜索引擎区分不同的目标输出。
- 安排更新，以确保包含可重复使用的新内容的不同文档实例不会以多周的间隔发布。
- 就最佳文章长度达成一致，这样相同的内容就不会出现在不同文档交付物的不同嵌套级别上。
- 考虑使用其他方法来区分不同类型的内容。例如，使用选项卡。
让我给你举个例子：
在这里，您可以创建三篇独立的文章，告诉用户如何在不同的操作系统上安装IntelliJ IDEA，每一篇文章都包含一些对重用内容的引用。然而，这实际上会用几乎相同的内容将受众拉向不同的方向，搜索引擎可能会将访问量最大的页面排名更高，这取决于哪种操作系统在IntelliJ IDEA用户中更受欢迎。
相反，您可以将这些类型的内容分成选项卡，以确保读者能够在同一页面上登录，并能够快速导航到他们需要的说明。
关键点
让我们总结一下JetBrains在经历了大约十年的内容重用陷阱后得出的结论。
- 每当你决定重用某些内容时，一定要权衡利弊。确保你让你的生活（或你同事的生活）变得更轻松，并且这是值得的。
- 在暗示复杂逻辑的可重用内容块之间创建依赖关系时要小心。旨在创建独立的可重用块，其逻辑不会因父片段的微小更改或对一堆相互覆盖的过滤器的修改而中断。在重用内容和保持源代码可读性和可维护性之间取得平衡。
- 记住，仅仅因为你能做到并不意味着你应该做到。不要误解“DRY”原则。有时，为了更简单的解决方案而牺牲完美的重用是明智的。
- 问问自己，您正试图通过内容重用来解决哪个问题。也许你会发现你的问题还有其他更简单的解决方案。想想我们的例子，我们建议通过在同一篇文章中创建模板、配置完成模式或在选项卡之间拆分类似内容来自动化日常工作。
- 请记住，当内容发布到网络上时，您的工作还没有完成。在您进行任何重大更改或发布任何新内容后，请始终检查它是否可被发现。归根结底，如果你的内容没有到达你的读者手中，那么它是否有用并不重要。
我们希望这些提示能帮助您负责任地重复使用内容！
