有关功能和技术文档的帮助

Question

我已经完成了一个Web应用程序，现在我想为其准备功能和技术文档。但我从来没有做过这样的文件。有人可以提供如何准备这种文件。

• 什么是被包含在功能和 技术文档 必要的点？

• 做这样的文件时需要考虑哪些因素 ？

Answer 1

Joel Spolsky通过series of blog post（4个职位）关于技术与功能文档。 他的系列专注于功能规格。

人提到的要点是的功能和技术规范的区别：

功能规范描述了一个产品将完全从用户的角度工作。它并不关心这个事情是如何实现的。它谈论功能。它指定屏幕，菜单，对话框等。

技术规范描述了程序的内部实现。它谈到了数据结构，关系数据库模型，编程语言和工具的选择，算法等。

他继续做出一个非常重要的观点IMO认为“规范是一个你想要的人阅读“和我的2c，并将继续阅读。

他还概述了许多有关功能规格内容的提示。整个系列是一个很好的阅读。如果我没有弄错，他还提供了一个示例功能规范的链接。

然而，在所有情况下，我认为你不应该遵循任何'规定'的方法来创建这些文件（包括乔尔的建议）。切实可行并创建容易阅读的文档和可维护因为我们都知道他们可以很快过时。听起来像我在谈论代码 - 但我想同样的原则适用。

这两套文档都会有不同的目标受众，所以知道你的目标受众。

一张照片上写着千言万语，所以使用简单图在适用的情况下。

我不想阅读有关系统做什么或如何工作的13卷系列。 所以要简洁。

文档结构很重要，但我建议不要着重于最初。理解并识别组成文档的所有小部分，并作为最后一步将其编译为可读文档。不要让目录驱动你的文档创建。首先将白色主意/区域/内容白板化。

每节应该有一个体面的介绍和结论。

Answer 2

我知道，如果你的软件已经建立了这个可能为时已晚，但你仍然可以去的“Zero Training”选项。

设计帮助和提示进入界面本身，以便用户不需要去外部地方获得他们需要的帮助。

有你的界面自我文档。如在中，让它足够直观，以便用户“知道”或可以“发现”自己如何工作。