技术文档框架

ref:: Technical Documentation Framework

教程(tutorials)：通过一系列步骤来帮助学习者正确的开始(类似教学)

• 学习导向
• 告知用户将取得的成就
• 确保用户获得同样的结果
• 确保用户立即看到结果，且结果是有意义的
• 教程可在不同的环境下复现
• 描述具体步骤，而不是抽象概念
• 仅提供最低限度的、必要的解释
• 忽略那些可能分心的选项和替代方案
• 语言框架
• 在本教程中，您将…
• 描述学员将完成什么（注意-不是：“您将学习…”）。
• 首先，做x。现在，做y。既然你做了y，就做z。
• 没有模糊或怀疑的余地。
• 在做y之前，我们必须总是做x，因为……（有关更多详细信息，请参阅解释）。
• 用尽可能基本的语言对行动进行最少的解释。链接到更详细的解释。
• 输出应该看起来像这样……
• 明确地向学员提供预期。
• 注意……记住……
• 给你的学习者提供充足的线索，以帮助确认他们走在正确的轨道上，并调整方向。
• 您已经制造了一个安全的三层透明稳态发动机……
• 描述（并钦佩，以温和的方式）你的学习者所取得的成就（注意-而不是：“你学会了……”）

操作指南(how-to)：解决一个具体的问题/实现特定的结果(类似食谱)

• 目标导向
• 不必从头开始，那是教程做的事
• 直观的标题《如何 xxx》
• 提供可实践的步骤/做法
• 注重结果，而非解释
• 实用可用性比完整性更有帮助
• 语言框架
• 本指南介绍如何…
• 清楚地描述要解决的问题。
• 如果你想要x，则做y。要实现w，则做z。
• 灵活。
• 有关选项的完整列表，请参阅x参考指南。
• 把概念解释交给参考指南，专注目标的实现。

参考(reference)：技术描述(类似wiki)

• 信息导向
• 简洁有序权威，只戳重点
• 使用内容相关的结构，有助于理解
• 语言一致性
• 仅描述
• 提供实例
• 保持准确
• 语言框架
• X是y的一个子函数。W需要使用z初始化。此选项可以做到这一点。
• 陈述有关选项及其行为。
• 子命令是：a、b、c、d、e、f。
• 列出命令、选项、操作、功能、标志、限制、错误消息等。
• 你必须使用a。除非c，否则您不得申请b。从来没有d。
• 酌情提供警告。

解释(explanation)：澄清和阐明特定话题，加深和拓宽读者对某主题的理解

• 理解导向
• 一种更轻松自由的思考某事的讨论方法。
• 已"关于"开头为标题
• 与相关的事物建立连接，编织理解网络
• 提供背景和具体例子
• 可讨论大局观/历史/选择、替代方案、可能性/为什么:原因和理由
• 避免提供指导做法或技术描述
• 语言框架
• x的原因是，从历史上看，y…
• 解释一下。
• W比z好，因为…
• 在适当的情况下提供判断甚至意见。
• 系统y中的x类似于系统z中的w。然而……
• 提供有助于读者的上下文。
• 一些用户更喜欢w（因为z）。这可能是一个好方法，但是…
• 权衡替代方案。
• x与y交互如下：…
• 揭开内部秘密，以帮助理解为什么某物会这么做。