Introduction
问题和解决方案
它解决的问题
不管你的产品有多好, 如果它的文档不够好, 人们就不会使用它. 尽管有些时候他们会因为别无选择而不得不使用这个产品, 如果没有好的文档, 他们也不会有效地使用它, 或者像你希望的那样使用它.
几乎所有人都懂这个. 几乎所有人都知道他们需要好的文档, 大多数人都试图创建好的文档. 但是大多数人都失败了.
通常来说, 这不是因为他们没有尽力而为. 通常来说, 这是因为他们没有用正确的方式去做.
这个系统是一种让你的文档更好的方式, 不是通过更努力地去做, 而是通过正确的方式去做. 正确的方式是更简单的方式 - 写起来更简单, 维护起来更简单.
"秘密"
它其实并不是一个秘密, 也绝对不应该是一个秘密: 文档需要包含并且围绕它的四个不同的功能: 教程, 怎么做指南, 技术参考和解释. 每一个都需要不同的写作方式. 人们使用软件的时候, 在不同的时间, 在不同的情况下, 需要这四种不同的文档 - 所以软件通常需要这全部四个, 并且它们都应该被集成到你的文档中.
而且需要明确地围绕这四个功能来构建文档, 并且它们都必须被分开并且与其他的文档相区分.
教程 | 怎么做指南 | 技术参考 | 解释 | |
---|---|---|---|---|
它面向 | 学习 | 一个目标 | 信息 | 理解 |
它必须 | 让新人上手 | 展示如何解决一个特定的问题 | 描述机制 | 解释 |
形式 | 一堂课 | 一系列的步骤 | 干巴巴的描述 | 论述性解释 |
比喻 | 教一个小孩如何做饭 | 烹饪书中的食谱 | 百科全书中的参考文章 | 一篇关于烹饪社会史的文章 |
这种划分使作者和读者都能清楚地看到什么材料, 以及什么样的材料该放在哪里. 它告诉作者如何写, 写什么, 写在哪里. 它使作者不必浪费大量的时间, 试图将他们想要传授的信息转化为有意义的形式, 因为这些类型的文档中的每一种都只有一个工作.
实际上, 维护好的文档, 不隐含或显式地承认这四个象限的方案是很难的. 每种类型的需求都不同于其他类型, 所以任何未能保持这种结构的文档尝试都会受苦, 因为它们同时被拉向不同的方向.
一旦你理解了这个结构,它就成为分析现有文档的一个非常有用的工具,并了解需要做什么来改进它。
在下面的章节中,将分别对这四个部分进行详细的论述。
使文档发挥作用
对于作者
文档维护者最头痛的问题之一是对他们应该做的事情没有一个清晰的认识. 他们写了又写, 但发现很难以令人满意的方式将其整合起来.
这种结构通过明确的区分和分离解决了这些问题. 它们使文档更容易编写和维护, 更容易使用, 更容易找到自己的方向.
文档并不会自己写自己 -- 但是现在有可能可以了, 而且不必再纠结于不合适, 不明确的范围或对应该包括什么或采用什么风格的怀疑. 写什么, 怎么写, 放在哪里, 都变得更加清晰.
对于读者
它能更好地服务于用户, 因为在他们与软件互动的周期中的所有不同阶段, 他们都能找到合适的文档,为当时的需求服务.
编写明确的, 针对四个象限中每一个象限的文档有助于软件吸引和保留更多的用户, 这些用户将更有效地使用软件 -- 这也是软件的创造者最希望的事情之一.