【.com速递】在移动应用、Web应用、桌面应用、JavaScript库开发领域，文档对保证产品服务效果的成功交付起着至关重要的作用。但是，如果您曾经处理过文档，您会同意我的看法：文档准备几乎是大多数开发人员从事的最不愉快的工作之一。对于开发者而言，不同于编写代码等本质性工作，他们需要交付清晰易懂的文档，甚至让读者能够轻松交流和分享。换句话说，他们应该跳出一直机器可以理解的代码思维，转而使用人类可以理解的表达方式。好的文档如何帮助用户显然，文档可以帮助读者理解您的代码是如何工作的。但是许多开发人员往往会陷入“知识陷阱”——错误地认为读者和他们一样精通目标代码。因此，他们在准备文档时可能会跳过很多点，并且不会从基础开始。如果读者懂相关的编程语言，还是能摸清来龙去脉的，否则自己摸索很容易迷路。通常，可供用户使用的文档需要显示一些实际用例，或有关如何使用软件产品的步骤。为了让读者尽快上手，开发者应该尽量使用那些通俗易懂的词语来代替各种专业术语来表达。如果他们能在此基础上提供一些实际的例子，那就更受欢迎了。同时，良好的文档排版设计还可以帮助用户快速跳转到实际需要的部分。Bootstrap和WordPress的文档《WordPress的第一步》都是这方面的优秀示例。好的文档可以帮助其他开发人员诚然，每个开发人员都有自己的编程风格，但在团队合作中，我们经常需要与其他队友共享代码。然后，为了就某个标准达成共识，团队中的每个开发人员都应该遵守相同的编程规范。而这样的规范往往建立在一个统一的文件中发布，供大家参考和遵循。与最终用户文档不同，此类文档通常需要清楚地描述技术过程，例如：代码命名规则、如何构造特定功能页面以及其API如何与代码示例配合使用。此外，我们还应该编写代码的内联文档（或注释）来描述代码的功能。同时，如果以后有新成员加入团队，这样的文档也可以大大减少他们的培训时间，我们也不必和他们一一讨论代码的细节。好的文档对自己的帮助在程序开发领域有一个很有趣的现象：几年甚至几个月后，开发人员可能一时半会儿看不懂自己写的代码段，需要花费一定的时间重读的时间。因此，在编写代码的过程中记录下相关注释，有助于你在敲代码时快速回忆起这段代码背后的编程思想和逻辑，以便立即改进或应用到其他类似的应用场景中。良好文档的组成部分和实践下面，我将讨论有助于您构建和开发优秀文档的五种实践：1.永远不要假设不要假设您的用户已经知道什么以及他们需要知道什么。也就是说，无论您的听众对您的代码的熟练程度如何，都要从头开始，从基础开始您的陈述。例如，如果你构建一个jQuery插件，你可以参考下面的SlickJS文档来展示如何构建HTML，在哪里放置CSS和JavaScript，如何初始化最基本的jQuery插件，以及添加各种元素后如何显示完成最终标记。可见，最重要的是写文档的思路应该从用户的角度出发，而不是从开发者的角度出发。只有这样整理你的文档，才会有更多的人愿意阅读和理解。2.遵循标准在代码中添加内联文档时，请参考相应编程语言的相关标准，清楚地描述每个函数、变量和函数返回值的期望。在这里，您可以参考以下PHP内联文档示例。如果你想了解更多关于不同编程语言的内联文档格式，请参考以下链接：PHP:PHPDocumentationStandardforWordPressJavaScript:UseJSDocCSS:CSSDoc另外，如果你使用的是SublimeText（译者注：A使用文本编辑器对于代码标记），我建议安装DocBlockr(https://github.com/spadgos/sublime-jsdocs)，它可以巧妙地将内联文档预填充到您的代码中。3、图形元素与文字信息相比，人们更容易接受图形元素。毕竟，谁不喜欢“有图有真相”呢？图文并茂的文档特别适合构建图形界面的软件。您可以添加方向性元素，如箭头、圆圈和其他任何能吸引用户注意力的元素，以帮助他们无需猜测即可确定要做什么。下图是名为Tower的应用程序示例。它有效地使用了一种易于理解的表示法来演示其基本操作方法。这显然比纯文本或命令行表达式更容易理解。4.切分可以考虑将文档中的一些内容打包，放在表头项或表格的单元格中。据此，我们不仅可以将长度改为较短，还可以方便用户在浏览完标题项后快速跳转到自己想阅读的内容。这类文档的制作步骤通常是：先添加简明扼要的标题目录，然后将文档按类别划分为不同的主题部分，最后将每个部分与相关标题相关联。下图是Facebook的一个结构良好的文档示例。我们只需要在右侧目录中点击要查阅的标题，相应的内容马上就会自动定位到左侧。5.修改更新最后，请大家在完成文档时认真审阅文字、图表，甚至各种表述中的错误。同时，当相应的软件、产品、代码库发生重大变更时，请及时修改相应的文档。显然，如果您的文档没有及时更新或不定期更新，它们不仅没有帮助，而且会误导用户。原标题：Web开发者文档的重要性，作者：ThoriqFirdaus
