java web开发技术文档的编写

技术文档分类：

分为开发（研发）文档和客户文档

开发文档：

项目开发过程中为了增加程序的可读性和程序的健壮性，方便后期程序的调试和维护，所以需要在开发过程中统一技术规范，一般会在项目初期确定好相关文档作为这一统一的规范。不同公司会对文档做不同要求，划不同的分类，但一般来说（或者拿自己的经验说）大致可以分为需求文档、接口文档、流程图（可以单独作为一份文件可以作为附件附在文档中）、变更文件等。

一、需求文档

在项目启动之后，项目的目标已经明确了，那么就要开始着手干活了，但是在干活之前，需要对整个项目分析透彻。那么，如何对业务进行分析呢，看以下的建议。

首先，开发人员要有随意转换身份的意识和能力。

A、明确产品功能

在分析业务时，站在用户的角度上，思考要做的产品能实现什么功能。把所有的功能点列出来！

B、分析某一功能点的流程

在罗列了所有的功能之后，需要站在开发者的角度分析每一个功能点，考虑从客户端到后台操作数据库的整个流程，可以从是什么、为什么、在哪、怎么做、谁来做、做完如何反馈、反馈给谁、上传到哪、服务器用什么数据库、数据库需要什么表、表里有什么字段、每个字段的属性及意义等等。比如，我要要做一个软件中个人头像上传的功能，首先明确我做的是上传功能；为什么要上传？因为个人资料需要头像；怎么做上传？通过网络I/O实现；这个功能在什么位置？软件有个个人中心模块，个人中心里有个个人信息子模块，在这个模块里可以上传头像；谁上传？已经登录的用户；上传完之后如何反馈？弹窗提示上传成功；反馈给谁？客户端已登录的用户；上传到哪？服务器上；用什么数据库？MySQL;需要什么表？（存到）用户表；表里有什么字段？用户信息的基本字段；每个字段的属性及意义？略。在思考完这些问题之后，可以把一个功能点串成一条完整的从前端到数据库的线。

C、整合各个功能点–明确分工

在串完所有的功能点之后，站在一个高一层次的角度，把每个功能点之间的联系理清楚，按照相互的联系分工合作，优化其中的细节问题。

D、撰写需求文档

分工完成之后，按照第二步分析的内容，每个人把自己负责的功能整理成文档，最后合并文档，作为统一的需求文档。

E、绘制业务流程图

需求文档确定之后，绘制整个项目的业务流程图，这时候的流程图只需要包含前端的业务流程，后台实现的流程图不需要在需求文档中体现，而是放在后面的接口文档中。

二、接口文档

不同公司对接口文档的要求也不尽相同，但包括的内容却是大同小异的。封面、标题、审批页、修订历史以及格式字体等等风格迥异的次要内容不做赘述，只讲干货！干货！干货！

A、请求地址

需要哪个线上地址就写哪个。注意不要反低级错误，比如写错某个字母或者大小写问题。

B、接口信息

说明请求方式，是POST还是GET。

C、功能描述

清晰地描述接口功能，要求言简意赅，不要写太多废话，也不要遗漏任何细节。

D、接口参数说明

声明参数的名称，严格要求与调用一致，包括大小写；

简单说明参数的含义；

参数的数据类型，是string 、int 还是long等（例如参数为@RequestParam(“appKey”) String appKey, @RequestParam(“randomId”) Integer randomId）；

备注部分，说明参数值是需要哪个公司提供，并详细说明参数怎么生成的，例如时间戳，是哪个时间段的；参数是否必填，一些参数是必须要有的，有些是可选参数，一定要注意写清晰。

E、返回值说明

有一个模板返回值，并说明每个返回参数的意义。提供一个真实的调用接口，真实的返回值。

F、接口调用限制

为了安全，双方采用一个一致的加密算法，保证接口调用的安全。

G、文档维护

文档维护时，修改内容部分需要有修改人、修改日期、版本号的信息。

三、流程图

流程图可以单独作为一份文件，也可以作为附件附在对应的文档中，具体执行按要求来。

业务流程图

程序结构图

程序流程图

四、变更文件

在开发过程中如果出现与预期计划、文档不一致的地方，则视为发生变更，此时大致需要提供以下信息：

A、版本历史（版本号、基本信息）

B、变更前现状

C、变更内容

D、影响评估

E、审批

客户文档：

指产品发布以后，公布给用户使用的文档。英文一般称为Customer Documentation。

文档详细解释产品的具体使用方法，安全提示，客户服务信息等。阅读对象一般为用户，技术支持工程师，售后服务人员。文档作为产品和市场接轨的桥梁，为产品的在市场上赢得客户的青睐，以及产品的长期发展做出了良好的保障。

要求

技术文档要符合以下要求:

1 针对性

文档编制以前应分清读者对象，按不同的类型、不同层次的读者，决定怎样适应他们的需要。

① 对于面向管理人员和用户的文档，不应像开发文档(面向软件开发人员)那样过多地使用软件的专业术语。难以避免使用的词汇，应在文档中添加词汇表，进行解释。

② 开发文档使用的专业词汇未被广泛认知的，应添加注释进行说明。

③ 缩写词未被广泛认知的，应在其后跟上完整的拼写。

2 正确性

① 没有错字，漏字。

② 文档间引用关系正确。

③ 文档细节(Title/History)正确。

3 准确性

① 意思表达准确清晰，没有二义性。

② 正确使用标点符号，避免产生歧义。

4 完整性

① 意思表达完整，能找到主语、谓语、宾语，没有省略主语，特别是谓语。

② 一句话中不能出现几个动词一个宾语的现象。

③ 不遗漏要求和必需的信息。

5 简洁性

① 尽量不要采用较长的句子来描述，无法避免时，应注意使用正确的标点符号。

② 简洁明了，不累赘冗余，每个意思只在文档中表达一次。

③ 每个陈述语句，只表达一个意思。

④ 力求简明，如有可能，配以适当的图表，以增强其清晰性。

6 统一性

① 统一采用专业术语和项目规定的术语集。

② 同一个意思和名称，前后描述的用语要一致。

③ 文档前后使用的字体要统一。

④ 同一课题若干文档内容应该协调一致，没有矛盾。

7 易读性

① 文字描述要通俗易懂。

② 前后文关联词使用恰当。

③ 文档变更内容用其他颜色与上个版本区别开来。

④ 测试步骤要采用列表的方式，用1)、2)、3)…等数字序号标注。（百度百科）

java web开发技术文档的编写相关推荐

Java web 项目技术文档目录结构
近期项目比较忙,没有更新文章,现在到了项目收尾阶段,正好在准备技术文档,所以把这个技术文档的目录和大家共享一下. 下面目录是我在参考了几个项目文档后自己总结出来的,每个章节之间不是递进关系(如四是对三 ...
Web 开发技术文档大全
https://developer.mozilla.org/zh-CN/docs/Web 基础 HTML CSS HTTP 脚本 JavaScript Web API 事件 Web Component ...
Java Web开发技术方案
Java Web开发技术方案 Java Web开发分前端.后端: Java Web前端: -就是在Web应用中用户可以看得见碰得着的东西.包括Web页面的结构.Web的外观视觉表现以及Web层面的交互 ...
java web 开发技术大全代码_Java Web开发技术大全
资深程序员全力打造,深入剖析SSH框架整合开发的精髓全方位解读Java Web开发的基础知识.高级技术及应用案例内容全面,讲解详细,全面覆盖JSP.Se rvlet.AJAX及SSH框架整合开发 ...
pythoncad二次开发视频_revit二次开发|bim软件二次开发|revit二次开发教程|Revit二次开发技术文档...
二次开发 revit二次开发|bim软件二次开发|revit二次开发教程|Revit二次开发技术文档2019-07-08赞( 0 ) 记录一下CAD二次开发的一些简单实例. 1.helloworld ...
Java Web开发技术教程入门-初识动态网页
这段时间学校搞了一个"阅战阅勇"的阅读活动,奖品还是挺丰富的~于是,奔着这些奖品,我去图书馆借了这本<Java Web开发技术教程>.一是为了那些丰富的奖品,二是为了回 ...
chrome vue.js插件文档_常用web研发技术文档，这里都给你准备好了
研发学习,工作过程中,技术文档是重要的工具之一,但是不少同学使用文档的姿势有点问题,遇到问题就一顿百度,拿着很多不一定对的博客文章翻来翻去还找不到答案,反而浪费了很多时间,我觉得解决日常问题更高效的方 ...
【渝粤题库】广东开放大学 java web开发技术形成性考核
题库查询系统选择题题目:当多个用户请求同一个JSP页面时,Tomcat服务器为每个客户启动一个_____. 题目:以下_____不是JSP运行所必须的条件. 题目:Tomcat服务器的默认端口为_ ...
服务器技术文件,服务端开发技术文档要包含什么？
[写在前面:为什么整理这个,因为我们很多开发写的技术文档真的是,,,所以希望日后随手提供开发一个自己需要的文档格式,培养写技术文档的能力,增进合作效率] 一.需求背景 1.需求文档链接 2.简要说明业 ...
读《Tomcat与Java Web开发技术详解》
作者: 孙卫琴, 李洪成编著出版社: 电子工业出版社出版时间: 2004-4-1 字数: 723200 版次: 1 页数: 438 印刷时间: 2004/04/01 开本: 印次 ...

java web开发技术文档的编写

java web开发技术文档的编写相关推荐

最新文章

热门文章