“云无界、端无边” OGeek 技术峰会 9月17日 南京不见不散! 了解详情
写点什么

不写文档你就输了

Web 开发者管理文档的重要性

  • 2020 年 9 月 22 日
  • 本文字数:2242 字

    阅读完需:约 7 分钟

不写文档你就输了

在移动、Web 和桌面应用或 JavaScript 库的开发领域中,文档在应用的成功之路上扮演着非常重要的角色。但如果你曾经编写过文档,就肯定会同意我的看法:编写文档是开发人员最不喜欢做的事情之一。


与编写代码(这是开发人员的本职工作)不同,文档必须能被所有人轻松理解(这里的所有人不仅是指开发人员,也包括缺乏技术背景的一般人)。从技术上讲,我们必须将机器语言(代码)翻译成普通人都可以理解的语言,这种事情说起来容易做起来却很难。


尽管这件事情可能会给你带来很大的负担,但是编写文档是很重要的环节,并且可以为你的用户、你的同事,尤其是你自己带来诸多好处。


好的文档可以帮助用户

显然,文档可以帮助读者 理解代码的工作原理。但是许多开发人员有着错误的认识,那就是他们认为软件的用户都是编程高手。在这样的假设下,他们编写的文档可能只是薄薄的几页纸,从头到尾跳过了文档本应该包含的许多要点。如果你精通编程语言,那么遇到问题还可以自己找出解决办法。如果你并没有那么专业,那么看文档时很容易就会迷失方向。


供用户使用的文档通常包括使用实践或“操作方法”的内容。为一般用户创建文档时,经验法则是 文档应该清晰直观。使用普通人也容易理解的词汇要比使用技术术语或专业习语更合适。软件的实际应用示例也是非常受用户欢迎的。


良好的文档布局设计还可以真正帮助用户轻松浏览文档的各部分内容。在这方面一些很好的例子包括 Bootstrap 的文档,和 WordPress 的“WordPress 的第一步”文档,它们也都是我最喜欢的榜样。


好的文档可以帮助其他开发人员

每位开发人员都有自己的代码风格。但在团队合作中,我们经常需要与其他同事共享代码。因此大家有必要 达成共识,形成一套标准,以使所有人保持一致。精心编写的书面文档会是团队必要的参考。


但与最终用户文档不同,这类文档通常会描述代码命名约定之类的技术流程,展示开发人员应如何构造特定页面,以及 API 如何工作,外加一些代码示例。通常,我们还必须在代码内编写文档(称为注释),以描述所注释代码的作用。


此外,如果以后有新成员加入团队,这类文档可以是培训他们的一种省时有效的方法,这样你就不必为新人一对一地讲解代码了。


好的文档也可以帮助开发人员自己

关于编程的有趣之处在于,有时 甚至开发人员自己也不理解他们编写的代码。尤其是当开发人员几个月甚至几年都没再碰过自己写过的代码时,他们突然回来看自己的作品会感到十分陌生。


如果出于某种原因,开发人员需要重新审阅以前的代码,他们往往会怀疑自己在编写这些代码时到底在想些什么。别惊讶:我以前就曾遇到过这种情况。在这种情况下,我肯定会希望自己给代码写下了良好的文档


给你的代码写好文档的话,你就能够快速深入到代码的底层,不会有那么多疑惑,从而节省许多时间。省下来的这些时间可以拿来完成更改工作。


好的文档有哪些特性?

有几个因素可以帮助你构建出良好的文档。其中一些最重要的因素如下:


1. 永远不要假设

不要以为你知道的东西用户也知道,或者他们很清楚自己应该了解的内容。无论用户的熟练程度如何,总是 从头开始解释各种事情 是更好的选择。


例如,如果你构建了一个 jQuery 插件,则可能会从 SlickJS 的文档中汲取灵感。它介绍了如何构造 HTML、放置 CSS 和 JavaScript 的位置、从头开始讲解如何初始化 jQuery 插件,甚至还展示了添加所有这些内容后的完整最终标记,所有东西都写得清清楚楚。



最重要的是,文档应该是根据用户而不是开发人员的思考过程来编写的。以这种方式处理你自己的文档,将为你提供一个更好的视角来组织自己的代码。


2. 遵守标准

在添加与代码内联的文档时,请使用 代码编程语言所期望的标准。 我们应该总是解释每个函数、变量以及函数返回的值都是什么意思。下面是一个很好的 PHP 内联文档示例。


/** * Adds custom classes to the array of body classes. * * @param array $classes Classes for the body element. * @return array */function body_classes( $classes ) {  // Adds a class of group-blog to blogs with more than 1 published author.  if ( is_multi_author() ) {    $classes[] = 'group-blog';  }
return $classes;}add_filter( 'body_class', 'body_classes' );
复制代码


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



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


3. 图形元素

文档中应该多用图形元素,它们比文本更直观。这些媒介很有用,特别是当你使用图形界面构建软件时。你可以添加指向性元素,例如箭头、圆圈或 任何可以帮助用户直观地弄清楚如何完成这些步骤的元素


以下是 Tower 应用中的示例,你可以从中汲取灵感。它们很好地解释了如何用优雅的方式来做版本控制工作,比纯文本命令行更容易理解。


4. 分区

你可以考虑将文档中的一些内容包装在项目符号列表和表格中,因为这样可以让用户更容易浏览较长的内容,更方便快速定位。


添加目录,并将文档拆分为一些容易理解的部分,同时要让各个部分与接下来的内容保持关联。内容应该简短明了。以下是 Facebook 中一份组织良好的文档示例


我们可以点击目录元素,直接跳转到对应内容。



5. 修订和更新

最后,文档写好后要仔细查看文档中是否有错误,并在必要时,或在产品、软件或库发生重大更改时修订文档。如果不随产品一起定期更新,那么你的文档对任何人都是没用的。


引文原文

The Importance of Documentation for Web Developers


2020 年 9 月 22 日 11:111629
用户头像
小智 前 InfoQ 主编

发布了 409 篇内容, 共 347.7 次阅读, 收获喜欢 1905 次。

关注

评论 1 条评论

发布
用户头像
我刚出来开发时,就是以开发人员的角度写的文档,一个组写出来的系统说明甚至不足一页……🤣
2021 年 01 月 07 日 16:36
回复
没有更多了
发现更多内容

Android NDK之旅——图片高斯模糊,30岁以后搞Android已经没有前途

android 程序员 移动开发

rabbitmq的死信队列

小鲍侃java

11月日更

Android Studio上Kotlin的入门,一次关于JVM的面试经历

android 程序员 移动开发

Android Launcher——ui框架,嵌入式音视频方向

android 程序员 移动开发

Flutter性能监控实践

贝壳大前端技术团队

flutter 性能 监控 优化

Android Retrofit 2,flutter游戏源代码

android 程序员 移动开发

iOS开发-百度一面总结

iOSer

ios iOS面试 ios开发 百度面试

Android Studio 模拟器卡慢、占内存解决方法,35岁技术人如何转型做管理

android 程序员 移动开发

android Jetpack Navigation组件——堆栈操作和动画效果

android 程序员 移动开发

Android Jsoup:实现HTML解析和Epub解析,论程序员成长的正确姿势

android 程序员 移动开发

墨刀发布企业版v3.5 ! 再度赋能“团队协同”新模式

Android OOM:内存管理分析和内存泄露原因总结,网易架构师深入讲解Android开发

android 程序员 移动开发

企业很难招到合适的员工,怎么办?

低代码小观

招聘 企业管理 企业招聘 招聘系统 招聘管理系统

Android Material Design尝鲜,阿里P8面试官都说太详细了

android 程序员 移动开发

会声会影VS剪映?免费虽好,但花钱的快乐你想象不到!

懒得勤快

Android PinnedHeaderListView 详解,flutter技术解析与实战

android 程序员 移动开发

android RoundedBitmapDrawable最简单方式实现圆角,事件分发机制流程图

android 移动开发

Android OKHttp 可能你从来没用过的拦截器 【实用推荐】

android 程序员 移动开发

《设计模式就该这样学》之使用策略模式重构电商折扣和支付场景

Java高级开发

程序员 设计模式 java

Android Studio 4,移动开发平台

android 程序员 移动开发

android LifeCycle-简单使用和详细原理解析,2021大厂Android面试经历

android 程序员 移动开发

耗时两个月,我终于把牛客网最火的Java面试题整理成册了,在Github标星60K

Sakura

Java 程序员 架构 面试 后端

Android MTK 设置默认启动 Launcher,android实战pdf

android 程序员 移动开发

2021年11月墨天轮国产数据库排行榜:openGauss闯入前三,Kingbase流行度与日俱增,TDengine厚积薄发

墨天轮

opengauss TiDB oceanbase 国产数据库

Android Studio 4(1),Android面试超详细知识点

android 程序员 移动开发

Android NDK 开发之 CMake 必知必会,后台开发Android岗

android 程序员 移动开发

Android R 新特性变化,三级缓存框架问题你都了解了吗

android 程序员 移动开发

Android RecyclerView的简单使用,我的阿里手淘面试经历分享

android 程序员 移动开发

Android Studio 3,android通知栏自响应事件

android 程序员 移动开发

首届腾讯云大数据峰会暨Techo TVP开发者峰会

首届腾讯云大数据峰会暨Techo TVP开发者峰会

不写文档你就输了_语言 & 开发_Thoriq Firdaus_InfoQ精选文章