文档对 Web 开发人员的重要性

已发表: 2021-03-02

在移动、网络和桌面应用程序或 JavaScript 库的开发领域,文档在决定应用程序的成功方面起着重要作用。 但是如果你曾经做过文档,你会同意我的观点,它几乎是开发人员最不喜欢做的事情。

与编写代码(开发人员签约要做的事情)不同,文档必须易于被每个人消化。 从技术上讲,我们必须将机器语言(代码)翻译成人类可以理解的语言,这比听起来更难。

虽然这可能是一个真正的负担,但编写文档很重要,并且可以为您的用户、您的同事,尤其是您自己带来好处。

学习编程:10 个不正确的误解

学习编程:10 个不正确的误解

关于编程艺术有很多误解和神话。 许多人认为这是一份工作……阅读更多

良好的文档帮助用户

很明显,文档可以帮助读者理解代码的工作原理。 但是许多开发人员错误地认为软件的用户会精通。

因此,文档可能很薄,从一开始就跳过了它应该包含的很多要点。 如果你精通语言,你可以主动想办法; 如果你不是,那么你就迷路了。

供用户使用的文档通常包括实际使用或“操作方法”。 为一般用户创建文档时的经验法则是它应该是明确的。 使用人性化的词语比技术术语或行话更可取。 实际使用示例也将不胜感激。

一个好的布局设计还可以真正帮助用户浏览文档的每个部分而不会造成眼睛疲劳。 一些很好的例子(也就是我最喜欢的)是 Bootstrap 和 WordPress 的“使用 WordPress 的第一步”的文档。

它可以帮助开发人员

每个开发人员都有自己的编码风格。 但是,当涉及到在团队中工作时,我们经常不得不与其他团队成员共享代码。 因此,必须对标准达成共识,以使每个人都保持一致。 正确编写的文档将是团队需要的参考

但与最终用户文档不同的是,该文档通常描述诸如代码命名约定之类的技术过程,展示应如何构建特定页面,以及 API 如何与代码示例一起工作。 通常,我们还必须编写与代码内嵌的文档(称为注释)来描述代码正在做什么。

此外,如果您以后有新成员加入您的团队,此文档可能是培训他们的一种省时有效的方式,因此您不必对他们进行一对一的代码检查。

开发人员应该采用的 10 个编程习惯

开发人员应该采用的 10 个编程习惯

这些结果可能会降低我们的信心,但实际上,它们可以通过适当的开发实践来解决......阅读更多

它还可以帮助编码员自己

编码的有趣之处在于,有时甚至开发人员自己也不理解他们编写的代码。 在代码数月甚至数年未受影响的情况下尤其如此。

出于某种原因突然需要重新访问代码会让人们想知道他们在编写这些代码时脑海中发生了什么。 不要感到惊讶:我以前也遇到过这种情况。 正是希望正确记录我的代码的时候

通过记录您的代码,您将能够快速且毫无挫败地深入了解代码的底部,从而为您节省大量可用于完成更改的时间。

什么是好的文档?

有几个因素有助于构建一个好的文档。 一些最重要的如下:

1. 永远不要假设

不要假设你的用户知道知道什么,以及他们想知道什么。 无论用户的熟练程度如何,从头开始总是更好。

例如,如果您构建了一个 jQuery 插件,您可能会从 SlickJS 的文档中获得灵感。 它展示了如何构建 HTML,将 CSS 和 JavaScript 放在哪里,如何在最基本的级别初始化 jQuery 插件,甚至在添加所有这些内容后显示完整的最终标记,这是显而易见的。

文档示例

最重要的是,文档是根据用户而非开发人员的思维过程编写的。 以这种方式处理您自己的文档将使您在组织自己的作品时有一个更好的视角。

2.遵循标准

在添加与代码内联的文档时,请使用语言的预期标准。 描述每个函数、变量以及函数返回的值总是一个好主意。 这是一个很好的 PHP 内联文档示例。

/**
 * 将自定义类添加到主体类数组中。
 *
 * @param array $classes body 元素的类。
 * @return 数组
 */
函数 body_classes( $classes ) {
	// 向拥有超过 1 个已发表作者的博客添加一个 group-blog 类。
	如果(is_multi_author()){
		$classes[] = '群博客';
	}

	返回 $classes;
}
add_filter('body_class', 'body_classes');

以下是一些使用 PHP、JavaScript 和 CSS 最佳实践格式化内联文档的参考资料:

  • PHP : WordPress 的 PHP 文档标准
  • JavaScript : 使用JSDoc
  • CSS : CSSDoc

如果您使用 SublimeText,我建议安装 DocBlockr,它会巧妙地使用内联文档预先填充您的代码。

WordPress 的编码标准 [指南]

WordPress 的编码标准 [指南]

我们有编码标准的原因(不仅仅是 WordPress)是为了创建一个熟悉的......阅读更多

3. 图形元素

使用图形元素,它们比文字更能说明问题。 这些媒体很有用,特别是如果您使用图形界面构建软件。 您可以添加指向元素,如箭头、圆圈或任何可以帮助用户确定去哪里完成步骤的元素,而无需猜测

以下是来自 Tower 应用程序的示例,您可以从中汲取灵感。 他们以一种令人愉悦的方式有效地解释了版本控制的工作原理,使其比使用纯文本命令行更容易理解。

4. 切片

您可以考虑将文档中的一些内容包含在项目符号列表和表格中,因为这样可以使用户更容易浏览和阅读较长的内容。

添加一个目录并将文档分成易于理解的部分,同时保持每个部分与接下来的内容相关。 保持简短明了。 以下是 Facebook 中组织良好的文档示例。 目录会带我们点击我们想要跳转到的地方。

文档示例 facebook
5. 修订和更新

最后,检查文档是否有错误,并在必要时或在产品、软件或库发生重大变化时进行修改。 如果不定期与您的产品一起更新,您的文档对任何人都没有用处。