好文档对于开辟者的紧张性

紫罗蓝蓝 · 发表于 2020-12-24 04:09:15

在移动APP、Web应用、桌面步伐、以及JavaScript库的开辟范畴中，文档在确保产物服务的乐成交付方面起着至关紧张的作用。但是，假如您曾经做过文档相干工作，那么您肯定会同意我的见解：文档预备险些是大多数开辟职员最不喜好从事的工作之一。

对于开辟职员而言，与编写代码之类的本质工作差别，他们必要交付出清晰易懂的文档，乃至可以让读者对其易于交换和共享。也就是说，他们应当跳出不停以来能让呆板明白的代码头脑，并转换为利用能让人类明白的表达方式。

好文档对于用户的资助

显然，文档可以资助读者明白代码的工作原理。但是很多开辟职员每每会陷入“知识陷阱”--错误地以为读者也和本身一样可以或许醒目目的代码。因此，他们在预备文档时，大概会跳过很多要点，而且并非从底子开始提及。假如读者相识相干编程语言，尚可弄清来龙去脉，否则端赖自行探索，很轻易会不知所终。

通常，那些可供用户利用的文档必要展示一些现实利用的案例，或是怎样利用软件产物的步调。为了让读者可以或许尽快上手，开辟者应只管利用那些用户友爱的词语，而非各种专业的术语来举行表述。假如他们可以在此底子上再提供一些实用的例子，则会更受接待。

同时，精良的文档结构计划，也可以资助用户快速地跳转到现实所需的部门。在此方面，Bootstrap和WordPress的文档《WordPress的第一步》都黑白常好的示例。

好文档对于其他开辟者的资助

诚然，每个开辟者都有本身的编程风格，但是在团队互助中，我们也常常必要与其他队友共享代码。那么，为了就某项尺度告竣共识，团队中的每位开辟者都应当服从雷同的编程规范。而此类规范，每每是创建在颁发同一的文档中，可供各人参考和遵照。

与终极用户文档差别的是，此类文档通常必要清楚地形貌诸如：代码的定名规则，怎样才气构造出特定的功能性页面，以及其API怎样与代码示例协同工作之类的技能过程。别的，我们还应该编写出代码的内联文档(或称为解释)，来形貌代码的功用。

同时，假如未来有新的成员参加团队，此类文档也可以或许大幅淘汰对其培训的时间，我们不必和他们逐条讨论代码的细节。

睁开全文

好文档对于本身的资助

在步伐开辟范畴有个非常风趣的征象：时隔几年、乃至几个月后，开辟职员大概一时无法明白本身编写过的代码段，而必要耗费肯定的时间重新研读。

因此，在编写代码的过程中随手记载下相干解释，将有助于您快速地追念起其时在键入此段代码时，背后的编程头脑与逻辑，从而可以或许立刻对其予以改进，或将其运用到其他雷同的应用场景中。

好文档的构成要素与实践

下面，我将和您讨论有助于您构建与开辟出良好文档的五项实践：

1.永久不要假设

不要假设你的用户已经知道了什么、以及他们必要知道什么。也就是说，无论受众将对您的代码具有何种纯熟水平，都请您重新开始、从底子开始报告。

比方，您构建了一个jQuery插件，那么就可以参照如下SlickJS的文档，展示怎样构造HTML，在那边放置CSS和JavaScript，怎样初始化jQuery 的最底子插件，以及在完成各种元素添加后，怎样表现完备的终极标志。

可见最紧张的是，文档的编写思绪应当从用户的角度出发，而不是站在开辟者的角度思索。只有从这种方式来构造您的文档，才气让更多的人乐意读，也读得懂。

2.服从尺度

在为代码添加内联文档时，请参照对应编程该语言的相干尺度，清晰地形貌每个函数、变量、以及函数返回值的预期。在此，您可以参照如下PHP内联文档的示例。

假如您想相识更多有关差别编程语言的内联文档格式，请参考如下链接：

别的，假如您正在利用的SublimeText(译者注：一款用于代码标志的文本编辑器)，我发起您安装DocBlockr(http://github.com/spadgos/sublime-jsdocs)，它可以或许将内联文档奇妙地预添补(pre-populate)到您的代码中。

3.图形元素

相对于文本信息，人们更轻易担当图形元素，究竟谁不喜好“有图有原形”呢?图文并茂的文档，尤其实用于那些用图形化界面构建的软件。您可以添加诸如箭头、圆圈、以及任何可以引起用户留意的指引性元素，来帮忙用户弄清详细操纵步调，而无需举行任何推测。

下图是一个名为Tower应用示例。它有用地运用了一种让人一览无余的体现方式，显现了其根本的操纵方法。这显然比纯文本或下令行的表述，要更轻易被明白一些。

4.分段

您可以思量将文档中的一些内容打包、并放置在某个标题条目、或表格的某个单位格中。据此，我们不光可以或许变长为短，而且同样可以方便用户在欣赏了标题条目后，快速地跳转到想要阅读内容处。

此类文档的制作步调通常是：先添加三言两语的标题目次，然后将文档分门别类地拆分为差别的专题部门，末了将每个部门与相干的标题对应起来。下图是Facebook的一个布局精良的文档示例，我们只需在右侧目次单击要查阅的标题，左边会立即主动定位到相应的内容。

5.修订和更新

末了，请在完成文档时，认真审视笔墨、图表、乃至是各种表述上的错误。同时，在对应的软件、产物、以及代码库发生庞大变动时，也请实时地修订对应的文档。显然，假如您的文档无法保持定期或实时更新的话，那么它们不光会无法实时地为用户提供资助，乃至会对用户起到误导的作用。返回搜狐，检察更多

责任编辑：