如何设计出用户喜爱的API

原文:User experience design for APIs
作者:Francois Chollet
译者:夜风轻扬

译者注:什么样的API才是好的API?如何开发出用户乐于使用的API?请阅读下文。

编写代码不仅仅是人与电脑间的事。代码也不只和电脑有关;还会影响到用户。程序员编写的代码会被其他程序员阅读、使用和维护。程序员只有使用顺手的工具,心情舒畅的时候才会写出更好更多的代码。不幸的是,他们常常会被难用的工具、晦涩的错误消息和不知所云的库弄的心烦意乱。(不好的)工具会给程序员带来痛苦,特别是在复杂的软件工程中。

用户体验(UX)应该在应用程序接口(API)设计中处于核心地位。一个设计优秀的API,会让复杂的任务变得简单,更会减少麻烦的产生。所以API用户体验设计完全不是多余的。为什么在程序员中缺少设计文化呢?
image

当程序员在电脑前编写代码的时候,用户对于他们来说是个抽象的遥远的概念。只有当他们和用户坐在一起,看到用户痛苦的使用自己编写的API时,才会意识到用户体验的重要性。现在是要重视用户体验的时候了,尽管大部分程序员还从来没做到。

另外一个问题是所谓的“聪明程序员综合征”。程序员会以为最终用户和他们一样拥有丰富的背景知识。但是,事实上,最终用户对API及其实现知之甚少。而且,聪明的程序员还会把问题搞得过于复杂,因为他们自己善于处理复杂问题。但是不够聪明或者是缺乏耐心的人呢?这就决定了软件不能太过复杂–超过特定的难度,就难以使用,用户就会排斥使用转而寻求更为清晰的方法。但是聪明的、有耐心的人呢?他们可以应付复杂事务,他们会不断的构造科学怪物。结果是生产出最差类型的API。

最后一个问题是一些程序员刻意使用敌视用户(user-hostile )的工具,因为他们将这种超级困难视为一种荣耀,而把设计贴心的工具看成是“给菜鸟用的”。在深度学习社区中这种态度尤为突出,在那里追求时髦和浮华。但是,这种自讨苦吃的态度最后只会弄巧成拙。从长远来看,良好的设计会占上风,因为好的设计会更有效率和影响力,会比敌视用户的负设计(undesign)更受欢迎。好的设计是有传染性的。

和大多事务类似,API设计并不复杂,只要遵循一些原则。而这些原则都源于一个基本准则:应该关心用户。所有的用户,而不只是其中聪明的人,不只是专家。任何时候都要重视用户。是的,包括那些首次使用的懵懵懂懂的用户,他们只有有限的背景知识,耐心也很有限。每一个设计理念都要从用户出发

对于API设计,这里有三个原则。

1-谨慎设计完整的用户流程

大多数的API开发者只关注单一的方法,而忽略了整体的流程。他们让用户自己摸索出完整的流程。由此产生的用户体验通常是一条长串的技巧,围绕着在各个方法层面上看不见的技术限制。

为了避免此种情况发生,一开始就要列出API使用的最常见流程。这些场景是大多数人都关心的。最好自己演练一下,并做笔记。更好的方式:观察新用户的使用,找出不足之处,并进行改进。特别的:
- 流程应该紧密映射到用户关心的特定领域概念
如果设计的API用于烹饪汉堡,很可能是诸如“肉饼”、“奶酪”、“圆面包”、“烧烤”等对象。如果设计深度学习API,核心的数据结构以及方法,应该映射到该领域用户所熟悉的概念:模型/网络、层、启动、优化器、损耗等。

  • 理想状态下,API元素不用处理实现细节。
    普通用户不会在意诸如”primary_frame_fn”, “defaultGradeLevel”, “graph_hook”, “shardedVariableFactory”, 或者 “hash_scope”,因为这些不是问题域中的概念,它们是内部实现中涉及的概念。

  • 谨慎设计用户的上手过程
    完全的新手如何利用工具来发现解决问题的最好方法?答案就是确保上手的材料是用户所关心的:不要教新手API是如何实现的,而是要告诉他们如何使用API来解决他们自己的问题。

2-减少用户的认知负担

在设计的完整流程中,应该减少用户理解和记忆的负担。用户的负担越少,在解决实际问题时就会使用的越多。—而不是花费精力去学习如何使用。特别的:

  • 使用一致的命名和编码模式
    API的命名约定在内部应该是一致的(如果通常用num_ 前缀来表示数值,就不要在一些场合改用n_),同时也要与外部广泛认可的标准保持一致。例如,如果设计用于在Python中进行数值计算的API,就不能明显的与广泛使用的Numpy API有冲突。敌视用户的API可能在Numpy使用keepdims的场景下使用 keepdim,也可能在Numpy使用axis的场景下使用dim,等等。设计糟糕的API可能对于同一个概念,随意使用axis、dim、dims、axes或者axis-i、dim-i等等。

  • 尽可能少的引入新概念
    新概念不仅是额外的数据结构,有一些新的方法和属性需要学习。而是需要更多的心智模型来掌握。最好只需要一种单一的通用心智模型(在Keras中是层/模型结构)。在流程中要必须避免使用超过2-3个心智模型。

  • 在类/函数的数量和参数间取得平衡
    每一用户操作的不同类/函数都会带来繁重的认知负担,增加参数同样如此。–谁都不想一个类的构造函数中有35个变量。可以通过数据结构的模块化和组合来达到这样的平衡。

  • 尽可能的自动化操作
    尽量减少流程中的用户操作。在用户编写的代码中找出经常重复的部分,并提供公用程序将其抽象化。例如,在一个深度学习API中,应该提供自动的形推论(shape inference)方法,而不是要用户去费力在所有层来计算期望的结果。

  • 要有清晰的文档,并附有大量的实例
    与用户交流如何解决问题的最好方式,不是简单的推论解决方案,而是把解决方案展示出来。对于API的每一个特点,都要有简明和可读的代码实例。

检验一个API是否设计优秀可以通过如下方法:
如果一个新用户在第一天使用该流程解决问题(借助文档或者教学),第二天在稍微不同的环境中,解决相同的问题时,他们不查看文档是否还能按流程进行?他们能否一次就记住流程?设计优秀的API中大部分的流程的认知负担非常小,简直可以过目不忘。
这个方法提供一种区分API好坏的方法,就是通过记录普通用户掌握某个流程过程查找文档的次数。最差的是那些经过大量学习还总记不住的流程。

3-给用户提供有帮助的反馈

优秀的设计是交互的。好的API在使用时很少会依赖文档和教学–只简单的按照直觉来尝试并根据API的提示来操作。特别的:

  • 尽早捕捉用户的和可预见的常见错误
    尽可能的进行用户输入验证。跟踪用户常犯的错误,或者是通过简化API、增加错误的提示信息来解决这些错误,或者是在文档中增加“解决常见错误”内容。

  • 为用户提供答疑的场合
    你有什么需要解决的问题么?

  • 为用户的错误提供详细的反馈信息
    一个完整的错误信息应该回答:在哪个环境中?发生了什么,软件期望的结果是什么?用户如何修复?这些应该是有语境的、有内容的和可操作的。为用户提供解决问题方法的错误信息得分,让用户不知所云的错误信息应该减分。

例如:
- 在Python中,下面就是个极坏的错误信息:

AssertionError: '1 != 3'

(一般经常使用ValueError而避免使用assert)
- 同样的坏信息还有:

ValueError: 'Invalid target shape (600, 1).'
  • 下面的要好一些,但是依然不够充分,因为没有告知用户通过了什么,也为告知如何修复:
ValueError: 'categorical_crossentropy requires target.shape[1] == classes'

下面是一个好的例子,提示什么通过了,期望是什么以及如何修复问题:

ValueError: '''You are passing a target array of shape (600, 1) while using as loss `categorical_crossentropy`.
`categorical_crossentropy` expects targets to be binary matrices (1s and 0s) of shape (samples, classes).
If your targets are integer classes, you can convert them to the expected format via:

--
from keras.utils import to_categorical

y_binary = to_categorical(y_int)
--

Alternatively, you can use the loss function `sparse_categorical_crossentropy` instead, which does expect integer targets.'''

好的错误信息会提高效率,也会抚慰用户的情绪。
link

结论

这些都是相当简单的原则,遵循这些原则会有助于开发出用户乐于使用的API。相应的,会有更多的人开始使用你的软件,这会有助于提高在领域中的影响。

要牢记:软件是为人而不是为机器服务的。任何时候都要把用户放在心中。


PS:推荐一个容器技术线上直播,讲师来自腾讯、华为、思科、58同城、蘑菇街、当当等6位一线专家,议题涵盖容器云、微服务、servicemesh等最新实践,欢迎报名参加
这里写图片描述

©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页