精华内容
下载资源
问答
  • 文档
    千次阅读 多人点赞
    2021-07-25 09:24:20

    本文大部分内容翻译总结自《Software Engineering at Google》 第10章节 Documentation。 另外,该书电子版近日已经可以免费下载了 https://abseil.io/resources/swe_at_google.2.pdf,有兴趣的同学可以下载翻阅下。 首先声明,本问所说的文档不仅限于纯文本文档,还包含代码注释(注释也是一种特殊形式的文档)

    在这里插入图片描述
    很多技术人自己非常轻视技术文档的书写,然而又时常抱怨文档不完善、质量差、更新不及时…… 这种在程序猿间普遍存在的矛盾甚至已经演变成了一个段子。
    在这里插入图片描述

    文档的重要性

    高质量的文档对于一个组织或团队来说有非常多的益处,比如让代码和API更容易理解、错误更少;让团队成员更专注于目标;也可以让一些手工操作更容易;另外如果有新成员加入的话有文档也会让他们更快融入……

    写文档有比较严重的收益滞后性,不像测试,你跑一个测试case,它能立即告诉你是对还是错,它的价值马上就体现出来了。而写一份文档,随着时间的推移,它的价值才会逐渐体现出来。 你可能只写一次文档,将来它会被阅读上百次、上千次,因为一份好的文档可以在未来替你向别人回答类似下面这些问题。

    1. 为什么当时是这么决策的?
    2. 为什么代码是这样实现的?
    3. 这个项目里都有哪些概念?
    4. ……

    写文档同样对于写作者也有非常大的收益:

    • 帮你构思规范化API: 写文档的过程也是你审视你API的过程,写文档时会让你思考你API设计是否合理,考虑是否周全。如果你没法用语言将API描述出来,那么说明你当前的API设计是不合理的。
    • 文档也是代码的另一种展现: 比如你两年后回过头来看你写过的代码,如果有注释和文档,你可以很快速理解代码。
    • 让你的代码看起来更专业: 我们都有个感觉,只要文档齐全的API都是设计良好的API,虽然这个感觉并不完全正确,但这两者确实是强相关的,所以在很多人眼里,文档的完善度也成为衡量一个产品专业度的指标。
    • 避免被重复的问题打扰: 有些问题你只需要写在文档里,这样有人来问你的时候你就可以让他直接去看文档了,而不是又给他解释一遍。

    为什么大多数人都不喜欢写文档?

    关于文档的重要性,每个技术人或多或少都知道一些,但很多人还是没有写文档的习惯,为什么? 除了上文中提到的文档的收益滞后性外,还有以下几点原因:

    • 很多工程师习惯将写代码和写作割裂开,不仅仅是在工作上,而且在思想上就认为它们是完全不相关的两项工作,这就导致好多人重代码不重文档。
    • 也有很多工程师认为自己不善写作,索性就不写了。 这实际是个偷懒的借口,写文档不需要华丽的辞藻、生动的语言,你只需要将问题讲清楚即可。
    • 有时候工具不好用也会影响的文档写作。如果没有一个很好的写作工具将写文档嵌入到开发工作流程中的话,写作确实会增加工作的负担。
    • 大多数人将写文档看做是工作的额外负担。 我代码都没时间写,哪有时间写文档!,这其实是错误的观念,文档虽然前期有投入,但能让你代码的后期维护成本大幅降低,磨刀不误砍柴工这个道理相信大家都还是能理解的。

    如何产出高质量文档

    既然理解了好文档的重要性,我们如何保证在时间的长河中维护好一份文档,这里有些相关的方法论,大家可以参考下。

    像管理代码一样管理文档

    对于如何写出好代码,整个技术圈已经有好多经验的总结了,比如书籍《重构》《代码简洁之道》…… 针对各种编程语言,也有相关的规范,比如国外的Google C++规范,国内的阿里Java开发规范等…… 但对于文档 似乎相关的资料却很少。但实际上,不应该把文档和代码割裂开来,你可以简单粗暴地认为文档其实就是用一种特殊语言书写的代码,这种语言就是人类的语言。这么想的话,实际上我们很多在代码和工程中总结出来的经验,也可以直接用在文档中,比如:

    • 有统一的规范
    • 有版本控制
    • 有明确的责任人维护
    • 有变更Review机制
    • 有问题的反馈和更新机制
    • 定期更新
    • 有衡量的指标(比如准确性,时效性)

    明确你的读者是谁

    写文档有一个很常见的错误,那就是很多人文档都是写给自己看的,这种情况下就会导致你的文档只有自己或者和你有相似知识背景的人才能看懂,团队较小时这种问题还好,你们都做着类似的工作,所以也都能看懂文档。但当团队逐渐壮大后,问题就会凸显出来,新人有时候有着和你不同的工作背景,甚至现在都做着不同的工作内容,这时候你之前写的文档他们就很难读懂了。

    所以在写文档之前请明确你文档可能的读者会是哪些人,然后针对他们的特点着重关注如何才能让他们理解。当然,文档也不一定要非常严肃和完美,只要能向你潜在的读者说明问题即可。 记住文档是写给别人看的,不是给自己看的。

    根据专业水平可以大致将读者分为三种 新手、老手和专家,针对不同水平的人写作需要有侧重点。比如针对新手,你需要重点介绍下里面涉及到的术语和概念,然后详细讲解具体的的实现。相反,针对专家 你可以省去这些额外的信息。注意,这里没有严格的标准,因为有些文章新手会看,专家也会看, 这里还是需要具体情况具体分析。

    另外一种对读者分类的方式就是根据读者阅读文档的目的来分类,比如有人知道自己遇到了什么问题,就是来找解决方案的。还有一批人只有一个简单的想法,但不知道具体的问题。举个例子,以读数据库慢为例,前者已经知道数据库慢可能是因为数据量巨大且没有加索引,解决方案很简单 加索引,这时候他可能需要知道的是如何正确地加索引。而后者可能着重关注的是为什么读数据库会慢,这时候你可能需要额外重点介绍下数据库相关的原理。

    清晰的分类

    文档大致可以分为以下几种类型,每种类型也有自己不同的特点和写作侧重点。

    参考文档

    参考文档也是大部分开发人员日常会使用和书写的文档,比如我们使用某个框架或者工具,都会有API说明文档,这就属于参考类文档。 它并没有太多的要求,只要能向读者展示清楚如何使用即可,但无需向读者讲明具体的实现。

    注:参考文档并不仅限于API文档,还包括文件注释、类注释、方法注释,要求都是能准确说明其用法。

    设计文档

    很多公司或者团队在项目开始前都要求有设计文档,设计是项目实施的第一步,所以在设计文档书写的过程中要求尽可能考虑周全,例如该项目的存储、交互、隐私……

    好的设计文档应该包含以下几个部分:

    1. 设计目标
    2. 实现的策略
    3. 各种利弊权衡和具体决策
    4. 替代方案
    5. 各种方案的优缺点

    写设计文档的过程也你对整个项目做规划、思考可能出现问题的过程,设计的越详细、思考的越多,未来遇到问题的可能性就会越小。

    引导类文档

    引导类文档也很常见,一般都是Step by Step的形式。比如我们在使用某个框架或者工具的时候,一般都会有个引导类的文档一步一步帮助你快速上手。 大家写引导类文章大家非常容易犯的一个错误就是预设了很多背景知识。 一般使用文档都是有开发者写的,他们都非常了解这个工具的相关的知识,所以习惯性的会认为,啊 这个知识点很简单 用户也肯定会吧,实际上用户不一定会。这本质上就是一种认知偏差,这种现象在跨团队协作 尤其是多端协作的时候也非常明显。

    这类型的文档写作中,要求写作者尽可能站在用户的视角上思考,极力避免出现和用户的认知偏差,力争每个步骤做到明确无歧义,每两个步骤之间做到紧密衔接。

    概念性文档

    当参考文档无法解释清楚某些东西的时候,就需要概念性文档了,比如某个API的具体实现原理。其主要是为了扩充参考文档,而不是替代参考文档。有时候这和参考文档会有些内容重复,但主要还是为了更深层次的说明某些问题、解释清楚某个概念。

    概念性文档也是所有文档中写作最难的,也是被阅读最少的,所以很多情况下工程师最容易忽视。而且还有另外一个问题,没合适的地方放,参考文档可以写代码里,落地页可以写项目主页里,概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。

    这类文档的受众会比较广,专家和新手都会去看。另外,它需要强调概念清晰明了,因此可能会牺牲完整性(可以由参考文档补齐),也有可能会牺牲准确性,这不是说一定要牺牲准确性,只是应当分清主次,不重要的就没必要说了。

    Landing pages(落地页)

    Landing pages就先简单翻译成落地页了,没想到啥恰当的翻译词。比如一个团队或者项目的导航页,虽然没啥具体的内容,但应该包含其他页面的链接。 比如你新入职一个团队,比较成熟的团队都会扔给你一个文档,这个文档里包含常用的工具、文档链接,这就是这个团队的落地页。
    落地页的问题就是随着时间的推移,页面可能会变的越来越乱,而且有些内容会失效,不过这些问题都好解决,做好定期的维护和整理就行。
    落地页的技术难度不高,但要求内容的有效性、完整性和分类清晰。

    文档Review

    在一个组织内,光靠个人去维护文档是不行的,必须得借助群体的智慧。在一个组织内部,文档的变更也应该像代码的变更一样,需要被其他人Review,以提前发现其中的问题并提升文档的质量。

    如何Review文档:

    • 专业的视角来保证准确性: 一般由团队里比较资深的人负责,他们关注的核心点是文档写的对不对,专不专业。如果Code Review做的好的话,文档的Review也属于Code Review的一部分。
    • 读者视角保证简洁性: 一般由不熟悉这个领域的人来Review,比如团队的新人,或者文档的使用者。这部分主要是关注文档是否容易被看懂。
    • 写作者视角保证一致性: 由写作经验丰富或者相关领域比较资深的人承担,主要是为了保证文档前后是否一致,比如对同一个专业术语的使用和理解是否有歧义。

    写文档的哲学

    上面部分站在组织和团队的视角来看如何提高文档质量,我们接下来看看站在个人写作者的视角上如何写出高质量的文档。

    5W法则

    5W法则相信大家已经听的多了,分别是Who What When Where Why,这是一个广泛被用在各行各业的法则,写文档当然也能用(5W法则堪称万金油,啥地方都能用)。

    • WHO: 前面已经说过了,文档是写给谁看的,读者是谁。
    • WHAT: 明确这篇文档的用途,有时候,仅仅说明文档的用途和目的就能帮你搭建起整个文档的框架。
    • WHEN: 明确文档的创建、Review和更新日期。因为文档也有时效性,明确相关日期可以避免阅读者踩坑。
    • WHERE: 文档应该放在哪! 建议一个组织或者团队有统一的永久文档存放地址,并且有版本控制。最好是方便查找、使用和分享。
    • WHY: 为什么要写这篇文档, 你期望读者读完后从文档中获得什么!

    三段式写作

    写文章一般都会有三个部分,专业写作者也讲究凤头、猪肚、豹尾,这三个词概括出了好文章三部分应有的特点。技术文档也算是文章的一种,所以一般也都会有这三部分,每个部分有其自己的作用,比如第一部分阐述问题,中间部分介绍具体的解决方案,第三部分总结要点。 但这也并不以为着文档应该有三个部分,如果文档内容比较多,可以将其做更细致的拆解,可以适当增加一些冗余的信息帮助读者理解文档内容。虽然很多工程师都讨厌冗余 极力追求简洁,但写文档和写代码不同,适当的冗余反而可以帮助读者理解,很简单,举个例子,比如写作中经常举例子,举的例子本质上就是冗余信息,生动的例子肯定是能帮助读者理解抽象内容的(我想这就是自举
    吧)。

    结语

    目前看到比较好的一个现象就是大家越来越重视文档了,但和测试相比 重视的程度还不够。测试已经是工作流程中不可或缺的一部分了,而文档依旧还不是。当然这可能和文档本身的特性相关,测试很容易被自动化,也有非常多的客观指标来评估。文档却做不到,首先文档的书写需要人手动介入,而文档的质量也没有太多客观的指标评估,提升文档的数量和质量只能从文化和工作流程上去逐渐改变。

    最后总结下本文几个关键点:

    • 随着时间的推移和组织规模的壮大,文档会越来越重要。
    • 文档也应该是开发流程的一部分。
    • 一篇文档只专注在一件事上。
    • 文档是写给读者看的,而不是给你自己看的。
    更多相关内容
  • 包含产品经理的PRD/BRD/MRD/角色分析/用户调查/用例分析等几十个文档,其中PRD还有完整的文档模板,教您如何书写。 【需求文档实例】内部资料.doc MRD市场需求文档.docx PRD产品需求文档.docx 产品路标规划实例.pptx...
  • java jdk 8 帮助文档 中文 文档 chm 谷歌翻译

    万次下载 热门讨论 2017-04-02 16:21:35
    JDK1.8 API 中文谷歌翻译版 java帮助文档 JDK API java 帮助文档 谷歌翻译 JDK1.8 API 中文 谷歌翻译版 java帮助文档 Java最新帮助文档 本帮助文档是使用谷歌翻译,非人工翻译。准确性不能保证,请与英文版配合使用 ...
  • 程序员项目交接文档

    热门讨论 2018-10-31 17:45:23
    程序员交接文档!IT项目交接文档概要
  • java jdk 8 帮助文档 中英对照版 中文 英文 文档 chm 谷歌翻译 文件打开空白 右键文件属性 解除锁定
  • 软件开发文档模板(全套)

    千次下载 热门讨论 2018-05-18 11:42:45
    1、可行性研究报告 2、项目开发计划 3、需求规格说明书 4、概要设计说明书 5、详细设计说明书 6、用户操作手册 7、测试计划 8、测试分析报告 9、开发进度月报 10、项目开发总结报告 ...13、软件修改报告
  • JAVA_API1.6文档(中文)

    万次下载 热门讨论 2010-04-12 13:31:34
    文档是 Java 2 Platform Standard Edition 6.0 的 API 规范。 请参见: 描述 Java 2 Platform 软件包 java.applet 提供创建 applet 所必需的类和 applet 用来与其 applet 上下文通信的类。 java.awt 包含...
  • 另外由于官方会不定期的更新官方的文档,更新也不会通知我,所以我制作API的时候也只能根据我所在时间点的官方文档作为翻译基础,而文档发布之后更新的内容自然不会出现在中文API当中,所以这就需要大家的帮忙和反馈...
  • 接口文档标准模板-含Word和excel两种

    热门讨论 2018-02-06 09:36:51
    接口文档标准的模板,包含Word和excel两种模板。满足各种语言接口需要。
  • Thymeleaf中文文档合集-最新版

    千次下载 热门讨论 2016-08-20 23:43:40
    Thymeleaf文档的合集,包括ppt,pdf等等,只要你想学,你要你想用,只要你看,你肯定会
  • 文档管理软件免费版

    热门讨论 2013-01-09 18:55:43
    深信文档管理软件可以将各类散落在不同的计算机上的文档的进行收集、整理归入一个统一的资源库,使用本软件能够把各种Office文档、PDF、图片等各类文件统一集中存放在服务器的数据库集中管理起来,非常方便文档再...
  • Mysql数据库文档生成工具

    千次下载 热门讨论 2016-02-16 22:21:52
    给大家介绍一款数据库文档生成工具 目前只支持mysql 主要是生成docx的 客户有些时候需要数据库文档,为了方便,于是我就写了这个工具, 通过数据库读取相关表数据,达到输出所有注释到文档中,大大提高了工作效率
  • javaAPI 官方文档 中文版 良心!
  • JDK8 中文帮助文档(jdk api 1.8 google.CHM)

    千次下载 热门讨论 2017-04-08 13:14:12
    JDK8 中文帮助文档(jdk api 1.8 google.CHM)
  • guava-API文档

    2015-03-20 21:04:20
    guava-API文档
  • QWT官方最新文档

    热门讨论 2014-10-17 16:08:50
    QWT官网最新版本文档,包含:授权、平台性、新特性、下载、安装、所有类API等
  • 接口文档与接口文档管理工具

    千次阅读 2021-07-12 11:16:45
    1.接口文档的定义:在项目开发汇总,web项目的前后端是分离开发的。应用程序的开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。 2.接口文档的...

    目录

    1、接口文档

    2、接口文档管理工具

    -Postman、Swagger、RAP、DOClever对比介绍

    3、Swagger

    总结


    1、接口文档

    1.定义:在项目开发汇总,web项目的前后端是分离开发的。应用程序的开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。
    2.功能与目的:项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护或者项目人员更迭的时候,方便后期人员查看、维护。
    3.接口文档规范:

    首先了解一下接口:

    请求方法GET
    PUT
    POST
    DELETE
    url以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;中间一般放表名或者能表达这个接口的单词。get方法,若果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾。uri地址里不逊于出现大写字母,如果是两个单词拼接,用/分开
    请求参数和返回参数字段类的属性
    说明中文释义
    类型属性的类型,只有String、Number、Object、Array四大类
    备注一些解释语,或者写简单的示例
    是否必填
    返回参数只返回接口调用成功或者失败:code、reason
    返回参数:字段、类型

    一份规范的接口文档除了上面提到的请求方法、url、请求参数、返回参数以外,还应该添加接口示例、接口文档版本号、版本修改内容、版本修改时间、修改人,错误代码等。

    5.示例:接口文档示例(来源:网络)

    2、接口文档管理工具

    -Postman、Swagger、RAP、DOClever对比介绍

    在项目开发测试中,接口文档是贯穿始终的。前后端开发需要在开发前期进行接口定义并形成文档,QA在功能测试和接口测试的环节也需要依赖于这些接口文档进行测试。接口文档往往以最简单的静态文档的形态存在。然而在紧张的敏捷开发模式下,随着版本迭代,很多接口发生了变化或者被废弃,而开发几乎不会在后期去更新这种静态文档。QA人员阅读“过期”的接口文档是一件痛苦的事情,与开发的沟通成本不降反升。而这些不便于及时维护的静态文档,随着时间的推移最终无人问津。因此,我们想要找到一种长期可维护且轻量便捷的接口文档工具。
    Postman是被大家所熟知的网页调试Chrome插件,我们常常用它来进行临时的http请求调试。幸运的是,Postman可以将调试过的请求保存到Collection中。形成的Collection就可以作为一份简单有效且支持在线测试的接口文档,使用同一账号登录就可以做到分享和同步。对QA来说,使用Postman进行接口测试和接口文档维护是同一件事情,测试即文档,维护成本也很低。

    Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案。Swagger主要包含了以下4个部分:

    1. Swagger可以直接嵌入项目中,通过开发时编写注释,自动生成接口文档;

    2. Swagger包含了SwaggerEditor,它是使用yaml语言的Swagger API的编辑器,支持导出yaml和json格式的接口文件;

    3. Swagger包含了SwaggerUI,它将Swagger Editor编辑好的接口文档以html的形式展示出来;

    4. Swagger支持根据定义的接口导出各种语言的服务端或客户端代码。

    其中1和4是更加面向开发的内容,开发团队要有自动生成文档的需求,在开发和自测中遵循前后端分离。而2和3是相对可以独立出来的、可供QA人员参考的接口文档管理方案,也是我们主要关注的部分。

    Swagger提供了SwaggerEditor和Swagger UI的在线demo,如下图。可以看出,Swagger可以完整地定义一个接口的内容,包括各个参数、返回值的具体结构、类型,SwaggerEditor可以实时进行编辑并在线调试。编辑好的API可以导出为json文件,使用Swagger UI打开即可以看到更美观的接口文档。

    Swagger Editor和SwaggerUI的本地部署十分简单,这两者都可以直接从Github上下载源码,将其部署到本地Tomcat服务器上,然后通过浏览器访问即可。官方还提供了其他几种部署方式,具体步骤在帮助文档中有详细说明,这里不再赘述。

    RAP是阿里的一套完整的可视化接口管理工具,可以定义接口结构,动态生成模拟数据,校验真实接口正确性。不仅如此,RAP围绕接口定义,提供了一系列包括团队管理、项目管理、文档版本管理、mock插件等服务。

    有关RAP的使用,RAP官网提供了非常详细的wiki和视频教程。与Swagger需要使用标记语言编写不同,RAP可以完全可视化地定义项目相关信息,定义接口的请求响应等等,学习成本较低。RAP还为后端开发人员提供了校验接口的功能,为前端开发人员提供了mock数据的工具等。

    DOClever是一个可视化接口管理工具,可以分析接口结构,校验接口正确性, 围绕接口定义文档,通过一系列自动化工具提升我们的协作效率。DOClever前后端全部采用了javascript来作为开发语言,前端用的是vue+element UI,后端是express+mongodb,这样的框架集成了高并发,迭代快的特点,保证系统的稳定可靠。

    功能如下:

    1.可以对接口信息进行编辑管理,支持get,post,put,delete,patch 五种方法,支持 https 和 https 协议,并且支持 query,body,json,raw,rest,formdata 的参数可视化编辑。同时对 json 可以进行无限层次可视化编辑。并且,状态码,代码注入,markdown 文档等附加功能应有尽有。

     2.接口调试运行,可以对参数进行加密,从md5 到 aes 一应俱全,返回参数与模型实时分析对比,给出不一致的地方,找出接口可能出现的问题。如果你不想手写文档,那么试试接口的数据生成功能,可以对接口运行的数据一键生成文档信息。

     3.mock 的无缝整合,DOClever 自己就是一个 mock 服务器,当你把接口的开发状态设置成已完成,本地 mock 便会自动请求真实接口数据,否则返回事先定义好的 mock 数据。

    4.支持 postman,rap,swagger 的导入,方便你做无缝迁移,同时也支持 html 文件的导出,方便你离线浏览!

    5.项目版本和接口快照功能并行,你可以为一个项目定义 1.0,1.1,1.2 版本,并且可以自由的在不同版本间切换回滚,再也不怕接口信息的遗失,同时接口也有快照功能,当你接口开发到一半或者接口需求变更的时候,可以随时查看之前编辑的接口信息。

    6.自动化测试功能,目前市面上类似平台的接口自动化测试大部分都是伪自动化,对于一个复杂的场景,比如获取验证码,登陆,获取订单列表,获取某个特定订单详情这样一个上下文关联的一系列操作无能为力。而 DOClever 独创的自动化测试功能,只需要你编写极少量的 javascript 代码便可以在网页里完成这样一系列操作,同时,DOClever 还提供了后台定时批量执行测试用例并把结果发送到团队成员邮箱的功能,你可以及时获取接口的运行状态。

    7.团队协作功能,很多类似的平台这样的功能是收费的,但是 DOClever 觉得好东西需要共享出来,你可以新建一个团队,并且把团队内的成员都拉进来,给他们分组,给他们分配相关的项目以及权限,发布团队公告等等。

    DOClever 开源免费,支持内网部署,很多公司考虑到数据的安全性,不愿意把接口放到公网上,没有关系,DOClever 给出一个方便快捷的解决方案,你可以把平台放到自己的内网上,完全不需要连接外网,同时功能一样也不少,即便是对于产品的升级,DOClever 也提供了很便捷的升级方案!

    官网: http://doclever.cn

    Github: https://github.com/sx1989827/DOClever

    码云: https://git.oschina.net/sx1989827/SBDoc

    文档: http://doclever.cn/help/help.html

    总结

    Postman是一个测试向的API小工具,可以非常轻量地维护一份“测试记录”,适合小的测试团队自己使用并维护。Swagger丰富且独立的各个功能使得它可以被应用在各种需求下,不论是开发还是测试都可以使用这个工具,来优化自己的开发过程,进行接口文档维护、接口测试等;但Swagger的学习和接入成本相对较高,需要开发与测试的深入配合。RAP的应用范围非常明确,是一个面向开发人员自测和联调的工具性平台,它更适合以开发为核心对接口进行维护,但目前基本不在维护。DOClever是一款功能比较强大的平台,在国内好评率很高,而且产品完全免费开源,可线下部署;同时产品更新迭代比较频繁,可以看出他们也是在用心做这个产品;

    3、Swagger

    swagger使用和教程_青春季风暴-CSDN博客_swagger使用

    相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。

    但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。





    1.说明

    现在SWAGGER官网主要提供了几种开源工具,提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

    在这里插入图片描述

    wagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

    Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

    Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

    Swagger Inspector: 感觉和postman差不多,是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据。

    Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。

    PS:

    Springfox Swagger: Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的,在这里列出来做个说明,方便后面作一个使用的展开。





    2.基于Spring框架的Swagger流程应用

    这里不会介绍Swagger的工具具体如何使用,不会讲yml或者json格式描述文件的语法规范,也不会讲如何在SpringMVC或者Spring Boot中配置Springfox-swagger。这些都能从网上找到,而且配置起来都非常的简单。

    这里想讲的是如何结合现有的工具和功能,设计一个流程,去保证一个项目从开始开发到后面持续迭代的时候,以最小代价去维护代码、接口文档以及Swagger描述文件。





    2.1 项目开始阶段

    一般来说,接口文档都是由服务端来编写的。在项目开发阶段的时候,服务端开发可以视情况来决定是直接编写服务端调用层代码,还是写Swagger描述文件。建议是如果项目启动阶段,就已经搭好了后台框架,那可以直接编写服务端被调用层的代码(即controller及其入参出参对象),然后通过Springfox-swagger 生成swagger json描述文件。如果项目启动阶段并没有相关后台框架,而前端对接口文档追得紧,那就建议先编写swagger描述文件,通过该描述文件生成接口文档。后续后台框架搭好了,也可以生成相关的服务端代码。





    2.1 项目迭代阶段

    到这个阶段,事情就简单很多了。后续后台人员,无需关注Swagger描述文件和接口文档,有需求变更导致接口变化,直接写代码就好了。把调用层的代码做个修改,然后生成新的描述文件和接口文档后,给到前端即可。真正做到了一劳永逸。





    2.3流程

    总结一下就是通过下面这两种流程中的一种,可以做到代码和接口文档的一致性,服务端开发再也不用花费精力去维护接口文档。




    流程一

    在这里插入图片描述


    流程二

    在这里插入图片描述




    给Mock系统的正常请求及响应全流程数据

    很多时候,如果你能在提供接口文档的同时,把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统,直接将这些模拟数据录入到Mock系统中,那将会提高前端的开发效率,减少许多发生在联调时候才会发生的问题。

    通过适当地在代码中加入swagger的注解,可以让你的接口文档描述信息更加详细,如果你把每个出入参数的示例值都配上,那前端就可以直接在接口文档中拿到模拟数据。相关的注解类及参数配置可以参考文末他人写的技术文章,这里也不作展开了。

    相关示例注解代码和效果图如下:#####Controller代码

    @Override
        @ApiOperation(value = "post请求调用示例", notes = "invokePost说明", httpMethod = "POST")
        public FFResponseModel<DemoOutputDto> invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {
            log.info("/testPost is called. input=" + input.toString());
            return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
        }
    

     #####接口请求入参对象  

    @Data
    @ApiModel(value="演示类",description="请求参数类" )
    public class DemoDto implements Serializable {
    
        private static final long serialVersionUID = 1L;
    
        @NotNull
        @ApiModelProperty(value = "defaultStr",example="mockStrValue")
        private String strDemo;
    
        @NotNull
        @ApiModelProperty(example="1234343523",required = true)
        private Long longNum;
    
        @NotNull
        @ApiModelProperty(example="111111.111")
        private Double doubleNum;
    
        @NotNull
        @ApiModelProperty(example="2018-12-04T13:46:56.711Z")
        private Date date;
        
    }

     #####接口请求出参公共类

    @ApiModel(value="基础返回类",description="基础返回类")
    public class FFResponseModel<T> implements Serializable {
    
        private static final long serialVersionUID = -2215304260629038881L;
        // 状态码
        @ApiModelProperty(example="成功")
        private String code;
        // 业务提示语
        @ApiModelProperty(example="000000")
        private String msg;
        // 数据对象
        private T data;
    
    ...
    }

     #####接口请求出参实际数据对象

    @Data
    public class DemoOutputDto {
    
        private String res;
    
        @NotNull
        @ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
        private String outputStrDemo;
    
        @NotNull
        @ApiModelProperty(example="6666666",required = true)
        private Long outputLongNum;
    
        @NotNull
        @ApiModelProperty(example="88888.888")
        private Double outputDoubleNum;
    
        @NotNull
        @ApiModelProperty(example="2018-12-12T11:11:11.111Z")
        private Date outputDate;
        
    }


    效果图

    模拟请求数据报文:
    在这里插入图片描述在这里插入图片描述
    模拟返回数据报文:
    在这里插入图片描述

    总结

    归根到底,使用Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件,连描述文件都不需要再去维护了。所有的信息,都在代码里面了。代码即接口文档,接口文档即代码。

    展开全文
  • Android4.4 API 文档 英文 CHM 版

    热门讨论 2015-02-05 17:17:07
    Android4.4 API 文档 CHM 英文版。使用官方的文档制作,但官方的文档会自动连接google网站,结果你知道的。 文档的源码已经经过修改,去掉自动连接google部分功能,绝对不会卡。 文件共180M,分三个压缩包,一定要...
  • web项目详细设计文档

    热门讨论 2015-10-09 11:47:37
    让初学web开发人员快速上手项目详细设计文档编写!
  • 并且会对这些插件做一些简单的Demo实现 存放到配套提供的程序包demo文件夹下 以便大家学习和使用 本期文档中将官方提供的所有附加插件的API都整理并存放到Extension节点下了 这些扩展的demo在附带的程序包中已经提供...
  • mui框架中文帮助文档

    千次下载 热门讨论 2015-12-22 18:26:20
    MUI 是一个轻量级的 HTML、CSS 和 JS 框架,遵循 Google 的 Material Design 设计思路,中文帮助文档
  • 需求文档

    万次阅读 多人点赞 2019-03-29 18:10:18
    相对于技术人员,他们不太关注产品的商业需求和市场愿景,因为在进行产品讨论立项时,产品的定义就已经向参与设计和研发的人员宣讲过,因此技术人员更多的是关注界面、功能、交互、元素等等内容,因此产品需求文档是...

    产品设计是一个由抽象的概念到具体形象化的处理过程,通过文字或图像等方式将我们规划的产品需求展现出来。它将产品的某种目的或需求转换为一个具体的物理或工具的过程,把一种计划、规划设想、问题解决的方法,通过具体的操作,以理想的形式表达出来。

    由于产品设计阶段要全面确定整个产品策略、外观、结构、功能,从而确定整个产品系统的布局,因而,产品设计的意义重大,具有“牵一发而动全局”的重要意义。如果一个产品的设计缺乏具体形象的表述,那么研发时就将耗费大量资源和劳动力来调整需求。相反,好的产品设计,不仅表现在功能上的优越性,而且便于执行时理解,从而使产品的研发效率得以增强。

    1、产品需求文档介绍

    产品设计的最终表述的形式被称为产品需求文档,业界常常称呼为PRD文档,这是英文Product Requirement Document的缩写。产品需求文档是将产品规划和设计的需求具体形象化表述出来的一种展现形式,主要用于产品界面设计和研发使用。

    PRD文档是基于BRD、MRD的延续文档,主要是一份给执行层面的工作人员阅读的文档,这部分人群绝大多数是设计与技术人员。在这类人群中,设计师更多依赖于产品原型进行交互或视觉的设计,因此看这份文档的人主要是技术人员。相对于技术人员,他们不太关注产品的商业需求和市场愿景,因为在进行产品讨论立项时,产品的定义就已经向参与设计和研发的人员宣讲过,因此技术人员更多的是关注界面、功能、交互、元素等等内容,因此产品需求文档是一份详细的产品功能需求说明文档,是产品文档中最底层和最细致的文档。

    因为阅读人类的因素,所以产品需求文档是一份没有闲话,直入主题的功能说明文档。并且产品需求文档是没有标准规范的,也没有统一的模板,每个公司都不一样和每个人也不一样,这个取决于个人习惯和团队要求。虽然产品需求文档没有明确的规范,但是目的都是一样的,必须能够明确产品的功能需求,便执行人员理解任务要求。

    2、产品需求文档写作

    产品需求文档是产品经过规划和设计之后的最终执行文档,因此这份文档的质量好坏直接影响到执行部门是否能够明确产品的功能和性能。

    2.1、罗列信息(信息结构图)

    在写产品需求文档之前,我们需要先罗列出产品功能的信息内容,这一步是将想法逐渐清晰的第一步,也是帮助我们接下来设计功能的辅助信息,同时也可以辅助服务端技术人员创建数据库。因为这是第一步,所以我们不需要罗列的很详细,在之后的步骤里,我们会逐步改进和完善信息内容。

    罗列信息内容的方式有很多种,文本形式、思维导图形式等等都可以,最主要的是能够清晰易懂,我最常用的方法就是使用思维导图软件(MindManager)罗列成结构图,因此我称这一步为“信息结构图”。

    shu-17

    上图是一张以Blog系统为示例的信息结构图。信息结构图是一种接近数据库结构的图表,在罗列信息结构时,更多的是考虑信息数据,但是他并不是真正意义的数据库结构。信息结构图是提供给产品经理自己梳理信息内容的结构图,也是方便产品经理和服务端技术人员沟通数据结构的参考图,技术人员会根据这张图表的内容再结合产品原型或需求文档,然后规划和设计出真正意义上的数据库结构。

    信息结构图中关于友情链接功能的信息数据只有“名称”和“链接”两个内容,但是在实际功能需求中,友情链接还有两个功能,分别是“显示或隐藏”和“是否新窗口打开”,这两个功能会在产品原型和需求文档中详细描述,但是在信息结构中是没有体现的,因为从产品层面上来说,这两个只是功能,并不是信息内容。但是在真正数据库中,友情链接的这两个功能分别也是有字段参数的,程序在读取该参数后便知道友情链接的属性,然后处理友情链接是显示还是隐藏,是新窗口打开还是本窗口打开。通过友情链接这个例子,我们就知道了在实际中数据结构和信息结构是不一样的,信息结构只是产品层面的数据内容。

    无论是什么样的产品类型,无论从哪里入手,我们第一步都是先要罗列信息结构,因为信息结构图不仅是辅助技术人员创建数据库的图表,也是辅助产品人员进行产品功能规划的参考,只有对信息或数据的结构了解了,我们才能更好的设计产品。

    信息结构图是我们将概念想法形成结构化的第一步,也是我们接下来几步工作的辅助文档,同时在接下来的几步工作中,我们还会不断的完善信息的结构。

    2.2、梳理需求(产品结构图)

    当我们对产品的信息结构了解后,我们就需要规整脑海中的产品需求,让想法更加结构化,因此这一步就要梳理产品的需求。在设计产品原型之前,我们首先要罗列出产品的功能结构,包括频道、页面、模块及元素。这一步依然使用思维导图软件,像绘制楼盘鸟瞰图一样将产品的结构绘制成结构图,因此我称这一步为“产品结构图”。

    产品结构图是一种将产品原型以结构化的方式展现的图表,结构内容也如同产品原型一样,从频道到页面,再细化页面功能模块和元素。所以产品结构图是产品经理在设计原型之前的一种思路梳理的方式,并不是给其他工作人员查看的文档,通过类似鸟瞰式的结构图可以让产品经理对产品结构一目了然,也方便思考。

    shu-18 shu-19

    如上图示例,“活动大全”的产品结构依次是:产品 -> 频道 -> 页面 -> 页面元素 -> 操作 -> 元素。我们换一个角度观看示例,产品结构图实际上就是一种结构化的产品原型。这样做的目的就是梳理产品结构逻辑,让我们清楚的知道产品有几个频道,频道下面有没有子频道或者有多少个页面,这些页面里又有哪些功能模块,这些功能模块里又有哪些元素。

    shu-19

    上图以我们第一步的“信息结构图”为基础绘制的“产品结构图”,有了这份结构导图,我们可以对产品进行鸟瞰式考虑和完善,当有问题时,修改起来也比原型和文档方便很多。比如在后续规划中,我们发现文章的图片等附件上传后,管理不太方便,这时就可以在结构图中增加一个“附件管理”频道。如果我们使用产品结构图的方式,那么附件管理的功能增加和修改就会比原型工具更加便捷和效率。

    产品结构图的方法同样适用于移动互联网产品的设计,并且比起Web产品更加容易梳理产品结构。

    产品结构图是一种让产品经理通过思维导图的方式梳理思路的方法,通过这种方法可以明确产品有多少个频道、有多少个页面、页面有多少个功能模块、功能模块有多少个元素,逐步的将脑海里的想法明确梳理成结构。虽然这种方法能够明确产品的结构,但是这样的思维导图也就只有产品经理自己能够看懂,因为对于设计和技术人员这是一个抽象的表述方式,如果没有详细的讲解,是很难理解的。

    产品结构图是将产品原型具体化的一种方式,只是罗列了产品的频道页面和功能,但是没有详细的进行推演,关于细化方面是否符合产品逻辑,是否符合用户体验,这些都是没有深思过的,因此我们接下来就要进行原型设计,开始具体的考虑可行性。

    2.3、原型设计(界面线框图)

    当我们逐渐清晰了产品的需求后,并梳理了产品的各个频道及页面,那么这一步就要开始验证这些想法的具体界面表现和方案的可行性了。

    原型设计是帮助我们更细致的思考,并做各项需求的评估,同时也是将自己脑海里的想法进行输出的一种方式。通过原型设计后,我们就可以进行产品宣讲了,相比较于抽象的文字描述,原型则更加直观的展现产品的需求,设计和技术人员或者老板也能够更加直观的了解到产品意图。

    原型设计是将结构化的需求进行框架化,因此原型也被称为线框图,具体的表现手法有很多种,相关的辅助软件也有很多,例如:Axure RP、Balsamiq Mockups、UIDesigner等等。

    当到了原型设计这一步时,已经不仅仅是构思了,我们需要更加深入的了解每个页面上元素和这些元素的属性。例如按钮元素,我们就需要考虑这个按钮的功能,并且这个功能操作后带给后端和前端的反馈。例如注册会员按钮,用户操作后,第一步逻辑是验证用户输入的信息是否合法,不合法则给出前端反馈;合法则和后端通信验证是否已经存在同样信息,已经存在则给出前端反馈,不存在则进入下一步,注册成功;注册成功后的反馈是跳转页面,还是弹出层提示用户完善资料,这些都是需要更详情的考虑。当然这些更细致的思考是留在需求文档撰写时的,而此时我们需要做的就是把这些元素通过原型表现出来。

    原型设计的表现手法主要有三种:手绘原型、灰模原型、交互原型。从工作效率的角度考虑,我非常建议先通过手绘的形式快速在草纸上绘制出产品的原型,推演和讨论方案的可行性。当方案的可行性被验证之后,我们再根据个人习惯或团队要求,通过软件工具进行更深入的设计。

    ① 手绘原型

    因为原型也被称为线框图,因此手绘是最简单直接的方法,也是最快速的表现产品轮廓的手法。

    手绘原型

    手绘原型在初期验证想法时非常高效,也方便讨论和重构,同时也适合敏捷开发时快速出原型。

    ② 灰模原型

    灰模原型是由图形设计软件制作而成,最常用的软件是Photoshop和Fireworks,相对手绘原型,灰模更加清晰和整洁,也适用于正式场合的PPT形式宣讲。

    灰模原型
    phone

    灰模原型也可以称之为平面原型,所以如果不会使用图形软件也可以使用Axure RP设计,相比交互原型,灰模原型只是缺少交互效果,仅仅是将产品需求以线框结构的方式展示出来,让产品需求更加规整的直观展现。

    shu-23

    ③ 交互原型

    交互原型是使用原型设计软件完成的原型,常用软件是Axure RP,通常情况交互原型的设计要早于产品需求文档,是产品经理想法推演的重要一步。通过Axure RP之类的交互原型软件制作出来的产品原型,在功能需求和交互需求的表现上,几乎和正式产品是一致的,所以有时交互原型也被称为产品Demo版。

    通常情况下交互原型是产品经理与交互设计师共同讨论确定,然后由交互设计师制作,但是绝大多数的公司是没有交互设计师这个职位的,因此这类工作最终是由产品经理来负责的。

    以上三种方法并不是渐进的流程,而是三种原型设计的方法,具体取决于你的产品需求和团队要求。

    对于产品经理来说,原型设计是为了帮助我们细致的考虑方案,并论证方案的可行性,同时也是为了产品宣讲时让听众能够清晰直观的了解产品,避免抽象的语言描述导致听众理解困难和理解偏差。产品原型也是为了确保产品在执行过程中,是按产品经理最初设想的需求和期望完成的,因此产品经理的原型是没有很高的要求的,只要对方能够听懂看懂就可以了,所以使用手绘原型是最高效率的方法。

    2.4、用例模型(产品用例图)

    用例(Use Case)是一种描述产品需求的方法,使用用例的方法来描述产品需求的过程就是用例模型,用例模型是由用例图和每一个用例的详细描述文档所组成的。在技术和产品的工作领域里都有用例模型的技能知识。技术人员的用例主要是为了方便在多名技术人员协同工作,或者技术人员任务交接时,让参与者更好的理解代码的逻辑结构。产品人员的用例主要是为了方便技术研发和功能测试时,让参与者更好的理解功能的逻辑。

    用例起源和发展于软件时代的产品研发,后来被综合到UML规范之中,成为一种标准化的需求表述体系。虽然用例在软件研发和技术工作中应用的非常广泛,但是在互联网产品规划和设计中,并不经常使用,互联网产品的需求表达为了敏捷效率,通常采用原型加产品需求文档。

    UML是英文Unified Modeling Language的缩写,中文称为统一建模语言或标准建模语言,是用例模型的建模语言,常用工具是Microsoft Office Visio。产品用例是一种通过用户的使用场景来获取需求的方式,每个用例提供了一个或多个场景,该场景说明了产品是如何和最终用户或其它产品互动,也就是谁可以用产品做什么,从而获得一个明确的业务目标。

    ① 用例图

    用例图并不是画成了图形的用例。用例图包含一组用例,每一个用例用椭圆表示,放置在矩形框中;矩形框表示整个系统。矩形框外画如图所示的小人,表示参与者。参与者不一定是人,可以是其它产品、软件或硬件等等。某一参与者与某一用例用线连起来,表示该参与者和该用例有交互。

    shu-24

    许多人通过UML认识了用例,UML定义为展现用例的图形符号。UML并不是为描述用例定义书写格式的标准,因此许多人误认为这些图形符号就是用例本身;然而,图形符号只能给出最简单的一个或一组用例的概要。UML是用例图形符号最流行的标准,但是除了UML标准,用例也有其它的可选择的标准。

    ② 用例描述文档

    用例图只是在总体上大致描述了产品所能提供的各种服务,让我们对于产品的功能有一个总体的认识。除此之外,我们还需要描述每一个用例的详细信息,这些信息应该包含以下内容:

    shu-25

    用例名称:本用例的名称或者编号

    行为角色:参与或操作(执行)该用例的角色

    简要说明:简要的描述一下本用例的需求(作用和目的)

    前置条件:参与或操作(执行)本用例的前提条件,或者所处的状态

    后置条件:执行完毕后的结果或者状态

    用例描述文档基本上是用文本方式来表述的,为了更加清晰地描述用例,也可以选择使用状态图、流程图或序列图来辅助说明。只要有助于表达的简洁明了,就可以在用例中任意粘贴用户界面和流程的图形化显示方式,或是其它图形。如流程图有助于描述复杂的决策流程,状态转移图有助于描述与状态相关的系统行为,序列图适合于描述基于时间顺序的消息传递。

    在互联网产品和设计中,用例的使用越来越少,通常有了产品原型再加上功能流程图和功能说明文档就能够将产品需求详细的表述清楚,所以也没有必须撰写用例了。但是在大公司里,往往会追求产品流程的规范性,要求撰写用例,不过在敏捷开发的时候也会采用其它更有效率的方式,不一定非要撰写用例。

    前面几步我们将产品需求逐渐细化并且通过原型的方式将产品需求形象化的展现了出来,但是在产品功能的逻辑细节方面,原型就非常不直观了,所以用例是一个非常重要的描述需求过程的文档。

    但是由于用例文档以文字为主,并且格式复杂,不适用于高效率的产品需求表述,所以展现逻辑流程的“功能流程图”是一个简洁直观的可替代用例文档的方式。

    shu-26

    (请点击查看大图)

    如上图所示,功能流程图是一种使用图形的方式表示算法逻辑的图表,因为千言万语不如一张图,通过流程图将“优惠券”功能模块的逻辑和需求非常形象直观、一目了然的展现了出来。

    流程图的展现方式也不会产生“歧义性”,便于理解,逻辑出错时也非常容易发现,并且可以直接转化为程序需求描述文档。

    2.6、需求文档(PRD文档)

    前面的几个步骤是为了帮助我们梳理需求、验证可行性和明确细节,到了这一步的时候我们已经非常清晰的了解产品需求,此时撰写产品需求文档可以大大减少和避免了撰写文档时容易忽略的细节黑洞。

    产品需求文档是将产品规划和设计的需求具体形象化表述出来的一种展现形式,主要用于产品界面设计和研发使用。因为每个人的习惯和团队要求都是不一样的,所以产品需求文档没有统一的行业规范标准,无论以什么样的格式撰写产品需求文档,最终的目的都是让执行人员能够理解产品需求,根据需求完成产品。

    产品需求文档的表现形式有很多种,常见的有Word、图片和交互原型这三种形式,文档内容通常包含信息结构图、界面线框图、功能流程图、功能说明文档。虽然产品需求文档没有标准的规范,但是有两项是必不可少的,那就是文件标识和修改记录。文档在撰写过程中,我们可以自行不断的修改完善,但是如果正式发布或交给团队其他成员后,一旦有了修改,为了文档的同步,我们就需要标注出文档的修改内容,备注修改记录,这样可以方便大家查看和了解改动的内容。关于文件标识和修改记录,格式都大同小异。

    prd

    ① Word

    这是传统意义上的产品需求文档,主要有四个部分组成(具体根据产品要求进行划分),分别是:结构图、全局说明、频道功能、效果图。

    因为产品需求文档的阅读者主要是偏向于技术人员,因此文档的目的性非常明确,就是要描述产品的功能需求,所有产品需求文档没有关于市场方面的描述。为了保证需求的执行效率,建议大家尽量减少不必要的文字,在能够让阅读者看懂并且了解产品意图的情况下,文字越少越好。这主要是因为绝大多数人是没有足够耐心认真看完产品需求文档的,因此我们要尽量减化文档内容。

    ①-1、结构图:

    ①-1.1、信息结构图:主要是辅助服务端技术人员创建或调整数据结构的参考文件

    ①-1.2、产品结构图:主要是辅助设计和技术开发人员了解产品的全局结构。

    ①-2、全局说明:

    主要讲解产品的全局性功能的说明,例如网站产品的页面编码、用户角色,移动产品的缓存机制、下载机制,这类全局性功能的说明。这里我举一个移动产品的“状态维持与恢复”的例子。示例如下:

    状态的维持与恢复

    当用户退出产品时(误操作、Home键、锁屏、自动关机),产品需要维持用户操作前的状态,当用户返回产品时仍可以恢复到之前状态,并继续使用。

    维持状态包括流程操作、信息浏览、文本输入、文件下载。

    锁屏状态时,如果用户在产品中有下载任务时,仍然保持下载。

    ①-3、频道功能:

    以频道为单位,页面为子项,分别描述产品的频道、页面及页面模块元素的功能需求。示例如下:

    1、频道名:频道介绍及需求说明

    2、页面1:页面介绍及需求说明

    2.1、页面模块1:模块功能需求说明

    2.1.1、页面模块1-元素1:功能说明

    2.1.2、页面模块1-元素2:功能说明

    2.2、页面模块2:模块功能需求说明

    在撰写功能需求时,我们需要考虑用户的流程,例如一个“完成”按钮,我们需要描述他完成后,系统要不要给出反馈提示(反馈提示是什么样的形式反馈,内容显示成什么,有没有内容需要调取数据库),或者要不要跳转页面(跳转到哪个页面,这个页面是其他频道页面,还是这个功能的子页面,如果是子页面就需要再描述这个子页面的模块及元素内容)。

    ①-4、效果图:

    效果图是由设计师完成的产品图,和实际开发完成的产品保真度一致。

    这个示例是一个移动产品(iPad)需求文档,其中部分隐私内容已过滤隐藏,并且只保留了首页和地图找房频道的需求说明。由于工作环境没有交互设计师,所以Word文档中包含了部分交互说明。

    ② 图片

    图片形式的产品需求文档是基于效果图的说明文件,将传统Word形式的功能需求说明标注在效果图上,这种方式经常使用在移动互联网领域,实际上是图文形式的交互需求文件,只是在此基础上更深入的描述出功能需求。

    对于图片形式的产品需求文档,我们只需要另外再描述一下全局说明,其他频道页面的需求直接以图片形式展示,这种方式相对于Word文档的纯文字更加生动易读并且直观,因此有一些产品经理非常喜欢用这种方式代替Word形式的产品需求文档。

    picture_prd

    ③ 交互原型

    这里指的交互原型就是前面篇章讲到的原型设计,使用Axure PR之类的交互原型设计软件制作出来的产品原型非常真实和直观,并且原型软件还支持元素标注和导出Word文档,因此很多产品经理都喜欢使用Axure PR来代替Word完成产品需求文档。

    当我们通过Axure PR制作出产品原型后,实际上他已经是很完善的产品Demo了,因此我们只需要加上元素的标注,在标注中说明功能需求,这样导出的HTML文件相比Word文档更直观易懂,是非常高效的产品需求说明方式。

    shu-31

    无论你采用哪种方式撰写需求文档,最终的目的都是为了方便团队成员理解产品的意图,因此哪种方法能够避免细节黑洞,高效完成产品的设计和研发,那么这种方法就是最有效的方法


    展开全文
  • ThreeJS中文API文档

    千次下载 热门讨论 2015-02-09 10:14:15
    原创 THREEJS 的中文API文档 作为大家分享
  • 前言、 一、注册飞书云文档账号、 二、创建云文档、 三、分享云文档

    前言

    最近发现一个比较方便的云文档 , " 飞书云文档 " , 如果要发布一个临时性的带 图片 , 表格 , 文件下载 的文档 , 推荐使用该工具 ;





    一、注册飞书云文档账号



    先输入手机号 , 点击注册 ;

    在这里插入图片描述
    设置企业信息 ;
    在这里插入图片描述

    设置个人信息 ,

    在这里插入图片描述
    验证手机号 ,

    在这里插入图片描述
    设置密码 ;
    在这里插入图片描述





    二、创建云文档



    进入 飞书云 后 , 点击 加号 按钮 , 选择 " 创建文档 " 选项 , 即可创建 云文档 ;

    在这里插入图片描述

    在编辑界面 , 输入文字 , 可以选择文字的样式 , 风格等 ;

    还可以添加 图片 , 视频 , 表格 , 文件 等信息 ;

    在这里插入图片描述





    三、分享云文档



    创建完毕 , 并编译文档 , 之后可以将该文档分享给别人 ;


    分享文档 : 点击右上角的分享按钮 , 可以设置分享权限 , 如 " 互联网上获得链接的人可阅读 " ,

    在这里插入图片描述

    确认权限 ;

    在这里插入图片描述

    这是分享的链接 : https://qungw4rfk5.feishu.cn/docs/doccnschOZGGhox5hldsNN7X4Ec

    展开全文
  • AutoCAD二次开发文档(C++ C# 史上最全版本)

    千次下载 热门讨论 2016-08-19 13:57:08
    目前收集到关于AutoCAD二次开发最全的文档。 也包括张帆 超清晰版PDF可复制代码的文档及源代码 还有.net CAD二次开发
  • Elasticsearch文档内部的父子关系

    千次阅读 2021-11-20 10:59:42
    Elasticsearch中的父子关系是单个索引内部文档文档之间的一种关系,父文档与子文档同属一个索引并通过父文档id建立联系, 类似于关系型数据库中单表内部行与行之间的自关联,比如有层级关系的部门表中记录之间的...
  • jQuery EasyUI 1.3.6 离线简体中文API文档

    千次下载 热门讨论 2014-04-12 00:07:07
    最新版本的jQuery EasyUI 1.3.6版全中文API汉化文档火热出炉,由于很多人和我要chm格式的,所以本次API我提供了2种版本的API,一个还是以前的EXE格式,另外一个就是人气颇高的chm格式。本次还将EasyUI 1.3.6版直接...
  • bootstrap帮助文档

    热门讨论 2014-01-14 14:29:00
    之前上网看不是很方便,新手压制的chm,需要的拿走吧。
  • ES系列之嵌套文档和父子文档

    千次阅读 多人点赞 2020-03-26 19:45:47
    需求背景 很多时候mysql的表之间是一对多的关系,比如订单表和商品表。...索引是独立文档的集合体。不同的索引之间一般是没有关系的。 不过ES目前毕竟发展到7.x版本了, 已经有几种可选的方式能...
  • Python3.2.3官方文档(中文版)高清完整PDF

    千次下载 热门讨论 2014-05-19 01:14:58
    Python3.2.3官方文档(中文版) 由笔者自己翻译,有不当之处希望在博客上相互交流

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 6,792,240
精华内容 2,716,896
关键字:

文档

友情链接: OptimCap-master.zip