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交互如下:…
- 揭开内部秘密,以帮助理解为什么某物会这么做。
发表回复