InfoQ 不写文档你就输了
作者|ThoriqFirdaus
译者|王强
策划|小智
在移动、Web和桌面应用或JavaScript库的开发领域中 ， 文档在应用的成功之路上扮演着非常重要的角色 。 但如果你曾经编写过文档 ， 就肯定会同意我的看法：编写文档是开发人员最不喜欢做的事情之一 。
与编写代码（这是开发人员的本职工作）不同 ， 文档必须能被所有人轻松理解（这里的所有人不仅是指开发人员 ， 也包括缺乏技术背景的一般人） 。 从技术上讲 ， 我们必须将机器语言（代码）翻译成普通人都可以理解的语言 ， 这种事情说起来容易做起来却很难 。
尽管这件事情可能会给你带来很大的负担 ， 但是编写文档是很重要的环节 ， 并且可以为你的用户、你的同事 ， 尤其是你自己带来诸多好处 。
好的文档可以帮助用户
显然 ， 文档可以帮助读者理解代码的工作原理 。 但是许多开发人员有着错误的认识 ， 那就是他们认为软件的用户都是编程高手 。 在这样的假设下 ， 他们编写的文档可能只是薄薄的几页纸 ， 从头到尾跳过了文档本应该包含的许多要点 。 如果你精通编程语言 ， 那么遇到问题还可以自己找出解决办法 。 如果你并没有那么专业 ， 那么看文档时很容易就会迷失方向 。
供用户使用的文档通常包括使用实践或“操作方法”的内容 。 为一般用户创建文档时 ， 经验法则是文档应该清晰直观 。 使用普通人也容易理解的词汇要比使用技术术语或专业习语更合适 。 软件的实际应用示例也是非常受用户欢迎的 。
良好的文档布局设计还可以真正帮助用户轻松浏览文档的各部分内容 。 在这方面一些很好的例子包括Bootstrap的文档 ， 和WordPress的“WordPress的第一步”文档 ， 它们也都是我最喜欢的榜样 。
好的文档可以帮助其他开发人员
每位开发人员都有自己的代码风格 。 但在团队合作中 ， 我们经常需要与其他同事共享代码 。 因此大家有必要达成共识 ， 形成一套标准 ， 以使所有人保持一致 。 精心编写的书面文档会是团队必要的参考 。
但与最终用户文档不同 ， 这类文档通常会描述代码命名约定之类的技术流程 ， 展示开发人员应如何构造特定页面 ， 以及API如何工作 ， 外加一些代码示例 。 通常 ， 我们还必须在代码内编写文档（称为注释） ， 以描述所注释代码的作用 。
此外 ， 如果以后有新成员加入团队 ， 这类文档可以是培训他们的一种省时有效的方法 ， 这样你就不必为新人一对一地讲解代码了 。
好的文档也可以帮助开发人员自己
关于编程的有趣之处在于 ， 有时甚至开发人员自己也不理解他们编写的代码 。 尤其是当开发人员几个月甚至几年都没再碰过自己写过的代码时 ， 他们突然回来看自己的作品会感到十分陌生 。
如果出于某种原因 ， 开发人员需要重新审阅以前的代码 ， 他们往往会怀疑自己在编写这些代码时到底在想些什么 。 别惊讶：我以前就曾遇到过这种情况 。 在这种情况下 ， 我肯定会希望自己给代码写下了良好的文档 。
给你的代码写好文档的话 ， 你就能够快速深入到代码的底层 ， 不会有那么多疑惑 ， 从而节省许多时间 。 省下来的这些时间可以拿来完成更改工作 。
好的文档有哪些特性？
有几个因素可以帮助你构建出良好的文档 。 其中一些最重要的因素如下：
1.永远不要假设
不要以为你知道的东西用户也知道 ， 或者他们很清楚自己应该了解的内容 。 无论用户的熟练程度如何 ， 总是从头开始解释各种事情是更好的选择 。
例如 ， 如果你构建了一个jQuery插件 ， 则可能会从SlickJS的文档中汲取灵感 。 它介绍了如何构造HTML、放置CSS和JavaScript的位置、从头开始讲解如何初始化jQuery插件 ， 甚至还展示了添加所有这些内容后的完整最终标记 ， 所有东西都写得清清楚楚 。
推荐阅读
- 极果果粉要哭了？苹果内部文档曝光，iPhone 12 双卡模式不支持 5G
- 威锋网|12双卡模式下无法启用5G，一份内部文档显示：目前iPhone
- 金山文档助力青岛疫情防控 安全高效赋能信息统计
- 电脑使用技巧Mac电脑如何使用MyZip压缩文件--帮助文档
- InfoQ12种Flutter开发工具推荐
- InfoQ一个IT时代的终结：109岁的IBM将分拆为两家公司
- InfoQ芯片断供，华为软件艰难补洞
- InfoQ不写文档你就输了
- InfoQ我是一位40岁的“老程序员”，我有一些想法
- |夏可叔叔扒产品——科颜氏超A面霜（推）