【软件开发】文档系统：文献大统一理论

为了编写好的软件文档，需要了解一个秘密：没有一种叫做文档的东西，有四种。

它们是：教程、操作指南、技术参考和解释。 它们代表四种不同的目的或功能，并且需要四种不同的方法来创建它们。 了解这一点的含义将有助于改进大多数文档——通常是极大的。

关于系统

此处概述的文档系统是一个简单、全面且几乎普遍适用的方案。它已在广泛的领域和应用中得到实践证明。

有一些非常简单的原则来管理文档，这些原则很少被阐明。它们似乎是一个秘密，尽管它们不应该是。

如果您能将这些原则付诸实践，它将使您的文档变得更好，并使您的项目、产品或团队更加成功——这是一个承诺。

该系统广泛用于大小、开放和专有的文档项目。

• 介绍
  • 问题和解决方案
    • 它解决的问题
    • “秘密”
  • 使文档工作
    • 对于作者
    • 对于读者
• 教程
  • 烹饪类比
  • 如何写出好的教程
    • 让用户边做边学
    • 让用户开始
    • 确保您的教程有效
    • 确保用户立即看到结果
    • 使您的教程可重复
    • 专注于具体步骤，而不是抽象概念
    • 提供最低限度的必要解释
    • 只关注用户需要采取的步骤
  • Divio 文档中的示例
• 操作指南
  • 烹饪类比
  • 如何编写好的操作指南
    • 提供一系列步骤
    • 关注结果
    • 解决特定问题
    • 不要解释概念
    • 允许一些灵活性
    • 把事情放在一边
    • 名称指导很好
  • Divio 文档中的示例
• 参考指南
  • 烹饪类比
    • 如何编写好的参考指南
    • 围绕代码构建文档
    • 始终如一
    • 除了描述什么都不做
    • 准确无误
  • Divio 文档中的示例
• 解释
  • 烹饪类比
  • 如何写一个好的解释
    • 提供上下文
    • 讨论替代方案和意见
    • 不指导或提供技术参考
  • Divio 文档中的示例
• 关于结构
  • 为什么这不明显？
  • 崩溃的趋势
  • 系统的采用
  • 关于分析及其应用
• 谁在使用该系统？
  • 其他提及和感兴趣的参考

原文：https://documentation.divio.com/

本文：https://jiagoushi.pro/documentation-systemp-grand-unified-theory-docume…