手机人、店、物联网

不写文档你就输了 - InfoQ -

   2020-10-07 1222910
核心提示:作者 | Thoriq Firdaus译者 | 王强策划 | 小智在移动、Web 和桌面应用或 JavaScript 库的开发领域中,文档在应用的成功之路上
作者 | Thoriq Firdaus译者 | 王强策划 | 小智

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

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

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

好的文档可以帮助用户

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

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

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

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

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

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

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

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

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

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

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

好的文档有哪些特性?

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

1. 永远不要假设

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

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

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

2. 遵守标准

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

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 的最佳实践来格式化内联文档的一些参考:

PHP:WordPress 的 PHP 文档标准Javascript:UseJSDocCSS:CSSDoc

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

3. 图形元素

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

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

4. 分区

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

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

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

5. 修订和更新

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


原文链接:http://www.hongkiat.com/blog/why-documentation-essential/

InfoQ 读者交流群上线啦!各位小伙伴可以扫描下方二维码,添加 InfoQ 小助手,回复关键字“进群”申请入群。回复“资料”,获取资料包传送门,注册 InfoQ 网站后,可以任意领取一门极客时间课程,免费滴!大家可以和 InfoQ 读者一起畅所欲言,和编辑们零距离接触,超值的技术礼包等你领取,还有超值活动等你参加,快来加入我们吧!




点个在看少个 bug 

随时随地 附近购物 采购批发 预约消费 到店取货 一件代发 上全信网

扫一扫分享到微信朋友圈

资源来源于全球各大网站平台,如有冒犯或者侵犯您的隐私或权利,请及时留言或者系平台,我们收到通知后会及时因情况严重予以删除或者下架相关内容

打赏
return $classes;}add_filter( 'body_class', 'body_classes' );

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

PHP:WordPress 的 PHP 文档标准Javascript:UseJSDocCSS:CSSDoc

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

3. 图形元素

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

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

4. 分区

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

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

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

5. 修订和更新

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


原文链接:http://www.hongkiat.com/blog/why-documentation-essential/

InfoQ 读者交流群上线啦!各位小伙伴可以扫描下方二维码,添加 InfoQ 小助手,回复关键字“进群”申请入群。回复“资料”,获取资料包传送门,注册 InfoQ 网站后,可以任意领取一门极客时间课程,免费滴!大家可以和 InfoQ 读者一起畅所欲言,和编辑们零距离接触,超值的技术礼包等你领取,还有超值活动等你参加,快来加入我们吧!




点个在看少个 bug "'/>

 
反对 0举报 0 收藏 0 打赏 0评论 0
 
更多>同类全信头条
推荐图文
搬离极高海拔 迎来幸福生活(走向我们的小康生活) 培养审美能力需用好互联网这个加速器
基层党建变思路 乡村振兴再提速 让每座城市放飞梦想(我与一座城)
“逛博物馆”成为新时尚(新数据 新看点) 美股科技股集体上涨 苹果涨超3%微软亚马逊特斯拉涨超2%
卓越的生命之花需要用美育浇灌 “百姓大舞台”带火乡村文化
古建保护有了新思路(金台论道) 国庆档电影《我和我的家乡》《一点就到家》引关注
如何在 Excel 中画出标准正方形? 导演陈可辛倾情说《夺冠》
东方之约 共享未来 让城市留下记忆 让人们记住乡愁
共创人类发展的美好未来 风姿万千 秘境囊谦
Win10 无法正确进行色彩管理?用 Honeyview 拯救 游客在神农架景区游览观光
山居古村 渐成“网红” 在气候环境问题上指责中方是无理的(钟声)
政策“组合拳”为企业送去“真金白银” 黑龙江:戍守边关家国心
一辈子环环相扣(收藏世界) 乡村手工坊 体验非遗乐
节日里的坚守 我国研发投入连续创新高
坚守岗位  奋战一线 思科在美被判专利侵权:需支付19亿美元赔偿金
福建东山:以生态建设为小康生活赋能加力 Cowen:苹果数字支付业务被低估,2022 年营收或突破 20 亿美元
让红色精神激发力量(今日谈) 群众在种植基地采摘葡萄
小鹏汽车收涨10.34% 单月与季度交付量创新高 枸杞红了 日子美了(全面建成小康社会 “百城千县万村调研行”)
美法官:思科必须支付 19 亿美元专利诉讼费 国泵民安  欢度国庆
浙江德清:家乡美景晒不够 全力做好景区安全和疫情防控工作
分享照片和视频 手机互传如何轻松搞定? 内蒙古发展现代能源经济初见成效
合肥加速打造制造业高地 舌尖上的致富路
黄河滩种出“冬枣第一村” 继续选派好驻村第一书记
勤俭节约过佳节 潜心研发终成正果
辽宁首开绥芬河口岸出境中欧班列 “跨界”老街重现繁华
SoC已快进到5nm 为何摄像头还在μm级 小微企业贷款更方便了
丝路古道绽放新风采 苹果 tvOS 14.0.2 发布:修复一些错误
滴滴出行旗下巴西叫车服务99与WhatsApp达成合作 雪川农业做精薯制品产业
联合国粮农组织:2020年农产品市场状况报告(164页) 中国在文莱最大投资项目拟投建二期工程
小鹏汽车收涨 10.34%,单月与季度交付量创新高 项目跟着能人走
以色列战机轰炸加沙地带哈马斯军事目标 合作和开放的大门向中国敞开
滴滴出行旗下巴西叫车服务 99 与 WhatsApp 达成合作 匈牙利国宝牛肉期待中国大市场
资产管理报告:支持增长并确保关照 青岛百亿元数字产业项目落地
LG 将推出 K系列第一款 5G 手机 K92:渲染图显示完整设计 人气旺盛 消费红火
小尾羊:让管理人员上一线练“内功” 绿色森林释放更多红利
酷派百元新机cool 12A首发:569元 待机14天 为城市新添天然氧吧
新型城镇化要在特色和品质上下功夫 胡须鸡带着“身份证”走市场
Digitimes:LG 首款折叠手机或采用京东方面板 创新社区治理的理念与模式
沪苏浙皖联手“云拼”大闸蟹 建乡村美丽家园
vivo X60 广告牌曝光,该机或将于近期发布 聚集低碳产业 提升空间品质
苹果 T2 芯片被发现存在不可修复的漏洞 三星 Note 20 Ultra DXO相机分数公布: 121 分,排名第十位
把党建优势转化为竞争优势 南京海关构建高效畅通物流体系
搬出生活新希望 百度计划发行有限票据 用于偿还现有债务
老黄称 RTX 30 系列显卡需求超预期,RTX 3080/3090 短缺问题将持续到明年 14000亿美元的大市场!贝索斯、马斯克纷纷斥巨资抢滩
恒天然25亿元出售中国牧场,三元现身奶源争夺战 美联储梅斯特寻求延长美联储购债期限的选择
Win 10 控制面板部分页面被删,原有功能怎么办? “理想自燃”“特斯拉车祸”…电动车更容易出事?别想多了
美联储埃文斯:必须把通货膨胀率提高到2%或更高,才能看到通货膨胀已经超出预期 她的两名助理也阳性!
豪气收购ARM后又一壮举:英伟达宣布将在英国建造超级计算机 电动汽车初创公司法拉第未来在商谈通过SPAC合并上市
神秘蓝光在毁掉你的精子 美国疾控中心:新冠肺炎病毒在室内的传播距离可以超过6英尺
怕尖端技术“流入中国”,日本想学美国? 大多数在赚钱,为何这些基金还亏钱?
2020年诺贝尔生理学或医学奖揭晓,“丙肝病毒的发现”摘得桂冠 欧盟将在2021年继续放松预算约束规则,以支持经济复苏
推荐全信头条
点击排行
申请链接  |  网址导航>
友情链接

按字母顺序分类

a      b      c      d      e      f      g      h      i      j      k      l      m      n      o      p      q      r      s      t      u      v      w      x      y      z     
随缘买
随机播
快递物流公司商务合作  |  我要开店 全信网商家入驻  |  贷款服务  |  在线提取抖因短视频工具(无水印)  |  办信用卡  |  常见问题  |  全信网小程序----让所有实体拥有自己的商城小程序、随时随地接单  |  信呗  |  急速到账  |  认领店铺  | 

  • 官方微信


  • 小程序

  • 官方微信客服


  • 官方APP

粤公网安备 44030902001450号


粤ICP备18107276号-2
聚合搜索