代码精进之路
范学雷
Oracle首席软件工程师,Java SE安全组成员,OpenJDK评审成员
立即订阅
6350 人已学习
课程目录
已完结 47 讲
0/4登录后,你可以任选4讲全文学习。
开篇词 (1讲)
开篇词 | 你写的每一行代码,都是你的名片
免费
第一模块:代码“规范”篇 (16讲)
01 | 从条件运算符说起,反思什么是好代码
02 | 把错误关在笼子里的五道关卡
03 | 优秀程序员的六个关键特质
04 | 代码规范的价值:复盘苹果公司的GoToFail漏洞
05 | 经验总结:如何给你的代码起好名字?
06 | 代码整理的关键逻辑和最佳案例
07 | 写好注释,真的是小菜一碟吗?
08 | 写好声明的“八项纪律”
09 | 怎么用好Java注解?
10 | 异常处理都有哪些陷阱?
11 | 组织好代码段,让人对它“一见钟情”
12丨组织好代码文件,要有“用户思维”
13 | 接口规范,是协作的合约
14 | 怎么写好用户指南?
15 | 编写规范代码的检查清单
16丨代码“规范”篇用户答疑
第二模块:代码“经济”篇 (14讲)
17 | 为什么需要经济的代码?
18丨思考框架:什么样的代码才是高效的代码?
19 | 怎么避免过度设计?
20 | 简单和直观,是永恒的解决方案
21 | 怎么设计一个简单又直观的接口?
22丨高效率,从超越线程同步开始!
23 | 怎么减少内存使用,减轻内存管理负担?
24 | 黑白灰,理解延迟分配的两面性
25 | 使用有序的代码,调动异步的事件
26 | 有哪些招惹麻烦的性能陷阱?
27 | 怎么编写可持续发展的代码?
28 | 怎么尽量“不写”代码?
29 | 编写经济代码的检查清单
30丨“代码经济篇”答疑汇总
第三模块:代码“安全”篇 (14讲)
31 | 为什么安全的代码这么重要?
32 | 如何评估代码的安全缺陷?
33 | 整数的运算有哪些安全威胁?
34 | 数组和集合,可变量的安全陷阱
35 | 怎么处理敏感信息?
36 | 继承有什么安全缺陷?
37 | 边界,信任的分水岭
38 | 对象序列化的危害有多大?
39 | 怎么控制好代码的权力?
40 | 规范,代码长治久安的基础
41 | 预案,代码的主动风险管理
42 | 纵深,代码安全的深度防御
43 | 编写安全代码的最佳实践清单
44 | “代码安全篇”答疑汇总
加餐 (1讲)
Q&A加餐丨关于代码质量,你关心的那些事儿
结束语 (1讲)
结束语|如何成为一个编程好手?
代码精进之路
登录|注册

14 | 怎么写好用户指南?

范学雷 2019-02-04
前一段时间,我要买一部家用的跑步机。有一款跑步机看起来配置齐备,商品的标题中指明“需要组装”。
商品的评论只有两条。其中一条给了三分:“还没有来得及试一试这个新到的跑步机。因为,我一直试着把它组装起来。我做梦都没有想到,‘需要组装’意味着我花了三天时间,都没有组装起来。它也许是一个好的跑步机,可是令人失望的是,这些零件到底该怎么凑在一起!”
而另一条则给了最低的一分。评论写道:“商品描述不准确。这台机器非常重,长度甚至超过两人沙发。一般的家庭根本放不下这台跑步机。已经退货了”。
你可以想象,这两条仅有的评论对这款跑步机的销售有多大的杀伤力。它本身的品质无论如何,都不至于沦落到一分、三分的地步。
问题在哪儿呢?无论是谁,花了三天时间都搞不定组装,肯定有一肚子的不满意。好不容易组装起来,却发现没有空间放置,又要拆掉退货,就会更不满意。
我了解了一下这款跑步机的用户手册,发现组装非常繁琐,所涉及的部件有很多,还真不是一下子就可以搞定的。
很显然,用户指南非常重要,但这款跑步机却给我们提供了一个反面的案例,可见写出一份好的用户指南也不是一件容易的事。
最好的用户指南,是产品本身。我们随手拿一只圆珠笔,就知道怎么用。然而,不是所有的产品都能够简单到拿来就用。一份合格的用户指南,要帮助用户减少产品使用的障碍,快速地使用产品。
取消
完成
0/1000字
划线
笔记
复制
© 版权归极客邦科技所有,未经许可不得传播售卖。 页面已增加防盗追踪,如有侵权极客邦将依法追究其法律责任。
该试读文章来自付费专栏《代码精进之路》,如需阅读全部文章,
请订阅文章所属专栏。
立即订阅
登录 后留言

精选留言(8)

  • 北风一叶
    我之前的主管给我的建议是这样的:你就把用户假定为啥也不理解然后再去写文档,写出来的文档就是合格的

    作者回复: 这是一个好办法。经常地,我们看一些文档,觉得废话太多,大量的篇幅交代背景。其实,哪是为了照顾更多的用户。

    2019-03-11
    2
  • kelvin
    我提出要给服务的接口写wiki,但是领导说大家都不会维护,还不如直接问接口维护人。我觉得维护文档是大家不太习惯,但是长远来看是可以提高开发效率。

    作者回复: 直接问接口维护人的问题很多: 接口维护人不一定时刻都在;接口维护人不一定有那么多时间;接口维护人不一定记得那么多细节;我们不一定想要面对面地提问;面对面问问题的效率有可能更低(复杂的技术问题需要问答双方都花很多时间)。

    2019-04-03
    1
  • 空知
    微信和Github的示例都只是提供示例,但是一些前提概念没有说明下吧.

    作者回复: 嗯,引用的是快速入门部分。

    2019-02-15
    1
  • 丁丁历险记
    身为py coder 我内心纠结之处,一直觉得java 反人类,经常一个简单事搞的啰哩巴嗦的,一度认为再好的设计模式也救不了java 的不优雅。
    甚至看到java 的代码示例看着就浅意识排斥。
    现在技术到了瓶颈期,在反思如何改善这些观点,我可以不喜欢,但个人鲁棒性需要加强。
    2019-10-14
  • Sisyphus235
    用户指南就像是开发者的 PPT,一个好的产品还要有一个漂亮的展示才能有价值。

    例证丰富能快速上手实践的往往是好的用户指南,在写文档的时候,文字和代码以及例证交叉,再配合一些图效果比较好,另外使用总分的结构效果比较好
    2019-05-22
  • Lindroid
    今年我也在GitHub上添加了两三个开源库(主要是供自己使用),不得不说写好说明文档真的是不容易的,而且比起最初的编写,后期的维护也考验人。

    作者回复: 😊经久耐用的软件,成本基本都在维护上。

    2019-04-27
  • 秦凯
    个人理解是:接口规范应该更多的是描述接口为什么这么设计,而用户指南更多的是指导用户如何使用接口,阅读的群体和功能上有区别。

    作者回复: 在 Java SE里,接口规范一般不包括“为什么这么设计”的描述。

    2019-02-15
  • vector
    简单明了,考虑全面。佩服别人家的手册。
    2019-02-08
收起评论
8
返回
顶部