开发之前需要哪些文档_为什么在开发之前总是应该做文档

开发之前需要哪些文档

程序员和项目经理有时认为“文档驱动的开发”是指在开发过程中在代码中添加大量注释或与文档编写者紧密合作。那是因为很难想象在编写文档之后开发将如何进行，因为肯定要等到实际编写文档后才能进行文档开发。

传统上，将文档视为一种新闻工作。为文档编写者提供了一些软件，他们将其带入实验室并对其戳戳并进行生产，直到他们弄清一切为止，然后将其写下来，以供他人阅读。

这错过了当开发人员一个晚上闲着喝咖啡，鼓吹一个应用程序的想法时自然发生的最重要的过程。开发人员可能没有意识到这一点，但是随着这个想法的形成，已经有一种文档在发生。想法并不会完全按照完整的蓝图绘制成完整的结构，准备挂接到单独的代码行上。想法逐渐发生。

代码可以说是一种艺术形式，因此这是艺术世界中的一个类比。

静物画代表物理世界中的某些事物。但是静物艺术首先是从抽象的形状开始，然后被精炼成可识别的东西，然后添加纹理，着色等等。

这个过程可以称为自我记录，因为在绘画生命周期的每个阶段，您都可以快照了解绘画的进展情况。

^{塞斯·肯隆（ CC0）}

在代码中，这些快照可能是git commits加上非常好的注释。虽然这对于以后加入并想了解代码库的哪个部分负责哪个任务的其他编码人员来说非常有用，但是对于一般的最终用户而言，它通常没有用。

在静物类比中，这意味着尽管绘画的自我证明对有抱负的艺术家可能有用，但对目标受众没有多大帮助。

绘画的最终用户文档实际上是最终的结果：绘画时画家看到的东西是绘画要捕捉的完全实现的图像。如果绘画的“最终用户”曾经想以最真实的形式理解绘画的主题，则最终用户指的是实际的物理对象。

信不信由你，代码也是如此。唯一的区别是所记录的应用程序尚不存在。但这几乎不意味着您无法像实际记录那样对其进行记录。

编写所需应用程序的文档

坐下来编写应用程序时，您会对应用程序打算做什么有所了解。我将以trashy实用程序为例，因为它的范围很窄：


Trashy is a command-line trash bin.

通常这正是开发人员开始的地方，但是，如果您练习文档驱动的开发，那么主页或用户手册就在这里开始，并且在您坐下来编写代码之前就发生了。

如果您唯一的任务说明是“编写命令行垃圾桶”，那么您的代码可能会朝着首先碰到您的方向发展。您可能知道或可能不了解Free Desktop垃圾回收规范，因此您可能一开始并不考虑遵循其计划。您可能已经知道有一个垃圾回收机制，因此您的代码的第一次迭代可能只是将文件转储到用户已建立的垃圾回收箱中，而无需考虑应该伴随它的相关元数据。

但是，如果您先坐下来记录下来，就会被迫考虑细节。例如，将其想象为垃圾分类文档的初稿：

Trashy is a command-line trash bin.

trash foo : moves foo to system trash trash empty : empties system trash

它已经比原始概念更强大，因为它还提供了一种清空垃圾箱的机制，而不仅仅是向其发送文件。唯一的原因是，记录用户与您的应用程序交互方式的行为迫使您从用户的角度考虑该应用程序。

这是绘画某些东西与将其实际悬挂在画廊墙上以供其他人查看之间的区别的干run。

`以文档为框架`

当您继续为命令行垃圾应用程序编写文档时，最终您会想到其他“显而易见的”期望，即您作为用户而不是开发人员对这种工具具有期望。您会想到一些约定，例如能够列出垃圾箱中当前有哪些文件，甚至还可以还原错误地移至垃圾箱的文件（这可能会导致您进入Free Desktop垃圾规范，这将使您了解将文件移至垃圾箱时应与文件一起写入的元数据）。

更好的是，您的文档现在是您的伪代码。您的应用程序开发已经从编写第一次修订时就被扔掉的代码变成了可以在其基础上构建代码的框架：

while [ True ] ; do

        # trash --help: print a help message

        if [ "$1" = "--help" -o "$1" = "-h" ] ; then

        echo " "

        echo "trash [--empty|--list|--restore|--version] foo"

        echo " "

        exit

        # trash --list: list files in trash

        elif [ "$1" = "--list" -o "$1" = "-l" ] ; then

        list

        shift 1

        # trash --version: print version

        elif [ "$1" = "--version" -o "$1" = "-w" -o "$1" = "--which" ] ; then

        version

        shift 1

        # trash --empty

        elif [ "$1" = "--empty" -o "$1" = "-e" -o "$1" = "--pitch" ] ; then

        empty

        # trash --restore: restore a file to original location

        elif [ "$1" = "--restore" -o "$1" = "-r" ] ; then

        RESTORE = 1

        shift 1

        # trashy foo: moves foo to trash

        else

        break

        fi

        done

# more code here...

`作为路线图的文档`

这是一个简化的示例，但是对于较大的项目，原理甚至更为重要，并且文档通常来自于同时也是开发人员的人。结果是开发周期更加集中，因为开发人员没有朝着模糊的应用程序概念进发，而是朝着确切说明应用程序应如何工作的特定蓝图进行编码。虚构应用程序的文档中已经映射了每个菜单，每个按钮，每个上下文菜单。开发人员所需要做的就是填写代码。

`敏捷之路战士`

如果所有这些听起来都非常明确和僵化，请不要假设使用文档驱动开发并不能应对敏捷挑战。敏捷的开发方法需要用户和利益相关者的反馈，以指导下一步的发展方向。文档不会改变这一点。实际上，在最佳的文档驱动的开发环境中，文档本身与源代码完全相同。它与其余源一起提交到同一存储库，并且在进行其他任何操作之前先进行更新。

实际上，将文档视为错误报告和功能请求的第一层是一种很好的保护项目免受UI蠕动的方法。当用户要求一个看似无害的UI更改（肯定是其他几个看似无害的更改的集合）时，UI可以Swift开始承载委员会设计的经典标记。这是因为，如果程序员添加请求的所有内容而没有通过具有全局视野的人员来审查它，则实际上是这样。

使用文档作为正在进行的设计过程的一部分是有意义的。这是便宜的原型。五个bug要求在主面板上一个新按钮意味着一个干净的一键式启动面板，等同于六个按钮使一次最小且干净的板块杂乱无章。但是，如果先记录并审查了起始面板，他们就不会将其从打印页面上移开。

就像编码一样，文档并不是在应用程序生命周期的早期完成的一次性过程。您的项目文档是与代码相同的有效文档，并且会不断更新和修订以反映开发计划和项目的当前状态。

`一致性`

文档往往会在应用程序的工作方式上产生一致性，因为内部逻辑已事先被很好地映射。

在应用程序开发的第一周内，将一个函数编码为单击按钮很容易，然后在UI上的空间非常宝贵的第八周，将同样重要的功能分配给晦涩的右键单击菜单。

当您为尚不存在的内容编写文档时，很难做到这一点。这在文档编制阶段都是虚构的，因此您将看到在为一个任务提供按钮但隐藏相关任务时违反逻辑。如果要修复它，只需花费一段很短的时间就可以很快地改写它，这与在多个文件中更改几个代码块完全不同，并且有可能重新制作您已经花费了数周的整个UI完善。当您只是在记录文档时，您可以编写任何您想要的东西；这是一种低成本的维修，最终为开发人员提供了更好，更智能的蓝图。

`立即试用文档`

关于文档驱动的开发，最大的好处可能是没有进入障碍。任何非编码人员都可以为不存在的应用程序发明文档，这非常有用。我在电影行业和教育领域编写的应用程序都是我以外的人设计的。当然，仍然有来回的用户测试和完善，这些东西在纸上看起来不错，但最终并未像设计者所希望的那样顺利地进行，但远不及没有设计者的情况。可以肯定的是，有时候非编码人员梦dream以求的东西超出了范围，必须被卷入其中，但有时这会导致开发人员学习一些新的技巧，以使某些以前无法想象的东西真正起作用。

无论您是开发人员，还是只是有一些好主意的用户，请坐下来并翻阅一些您想看到的应用程序的文档。或者，为您认为可能更好的现有应用程序版本编写一些文档。它会在多大程度上影响您对软件，直观设计和开发的思考方式，您会感到惊讶。

翻译自: https://opensource.com/article/17/8/doc-driven-development

开发之前需要哪些文档