如何设计良好的技术项目文档结构
Posted 老张的求知思考世界
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了如何设计良好的技术项目文档结构相关的知识,希望对你有一定的参考价值。
前言很多技术同学在日常的工作中接触到的大多是TO C的业务或者对外业务,由于大多数企业的主要营收是来自外部用户,因此内部的一些项目不会有太规范的流程和太高的要求标准。什么高可用高性能都是扯淡,良好的用户体验根本不存在。如果是一些内部的技术项目,特别是一些基础技术设施的技术项目,反而对技术要求是比较高的。
我目前在基础架构团队负责内部技术项目的一些工作,包括产品设计、交互逻辑、撰写PRD、项目管理以及测试工作。
这篇文章,想和大家聊聊,技术项目中一个良好的文档结构如何设计。
思维导图
一般来说技术项目可以分为四大阶段,本篇文章我会从四个阶段分别来介绍,在不同阶段需要设计哪些项目文档。
项目管理
无论是TO C的外部业务需求迭代还是内部的技术项目,项目管理是必不可少的事情。这里我想介绍下面三点我个人认为在项目管理中比较重要的点。
流程规范
流程规范相关的话题,我在之前的文章《测试工程师的职场发展二三谈》中做了很长篇幅的描述,这里再次重温下。
问:流程是什么?为什么要有流程?流程能解决什么问题?流程能带来什么保障?
流程是什么?
流程是保障团队目标达成的最佳实践,因人/团队/业务类型/迭代速度/资源紧张程度而异。
为什么要有流程?
没有流程会导致团队中的个体各自为战,目标不统一,进度不协调,资源配给失衡而导致交付质量下降。
流程能解决什么问题?
流程能保障团队或者群体在大方向上保持协调一致,尽可能降低由于团队人员能力、认知水平、资源不足、意外情况导致的项目延期或者质量下降。
流程能带来什么保障?
流程可以保障你可以有底气的据理力争,虽然不一定能扭转局势,但在一定层面上,会哭的孩子有奶吃,偶尔学会受委屈给领导看,也是以退为进保障自己利益不受太多损失的技巧。
流程规范的价值:风险可识别+问题可追踪+结果可验证+数据可量化!
写博客的老张,公众号:老张的求知思考世界测试工程师的职场发展二三谈
上面引用了之前对流程规范的一些描述,在具体的项目管理中,常见的流程规范有如下几种:
需求评审流程
方案评审流程
功能提测流程
发布变更流程
信息同步流程
项目复盘流程
迭代记录
目前在我负责的项目中,采用的是敏捷迭代机制,每周都会交付一个版本,可以是新功能上线,也可以是功能优化。
敏捷迭代模型的核心是快速交付可用的质量有一定保障的产品,让用户给到反馈和建议,不断迭代,不断满足用户新的需求,直到最终交付一个比较成熟的技术产品。
这种模型比较适用于内部或者需求不明确的项目;如果是需求明确对质量有高要求的,反而不适合这种迭代交付模式。而迭代记录,是将每次迭代的内容,通过小的内部版本号进行记录。它的作用有两点:
记录每次交付内容,向上有交代,对外有信心(即领导知道你在做什么,用户知道你再不断满足他们的需求);
定期复盘的素材,通过定期复盘迭代交付过程的内容,找到做的不好的点,避免在后续迭代中犯错踩坑;
会议记录
一般这种内部技术项目,流于形式的务虚内容可以尽量减少,但下面两点我个人觉得是很有必要保留和执行到位的。
进度追踪:内部宣讲形成习惯,每天更新今天的进度,遇到的问题风险,评估是否需要调整优先级和迭代计划;
周报汇总:虽然说写周报我个人觉得是个很智障的事情,但这也是一种管理手段。我们不能祈求所有人都具备良好的职业素养和较高的自觉性,只能通过一些流程规范去尽可能降低和避免带来的问题。而且,周报也是向上管理的重要方式!
四大阶段
启动阶段
项目概述:即为什么做这个项目?背景是什么?要解决什么问题?面临哪些风险?项目的价值是什么?
项目规划:长期规划是什么?分几个阶段实现?每阶段重要产出物和里程碑是什么?如何量化评估每个阶段的交付物?
设计阶段
原型图:即这个技术项目的web页面或者后台管理页面,交互逻辑等。
需求调研:一般内部的技术项目,需求大多来自内部其他部门或团队。在设计阶段尽可能多的进行需求访谈是很重要的一件事。多去听用户的痛点是什么,他们想要什么,然后将用户需求转化为产品需求。
PRD文档:PRD是需求的最终产出物,有了PRD才能开展后续的如需求评审、架构设计等工作。
研发阶段
研发阶段实际上要做的事情是很多的,下面列举几项比较重要的需要产出的文档。
架构设计:架构设计即项目的技术实现方案,包括功能架构图、系统技术架构图、环境配置、各项参数等重要信息说明。
接口文档:接口的作用是约定数据的交互逻辑和出入口,也是功能联调和测试阶段需要重点关注的对象。
测试用例:没有一个产品是不需要测试验证的,测试用例的最大作用是验证产品实现是否是按照预期设计来实现的。
BUG列表:记录问题的本质,是梳理和复盘产品不足之处,并快速加以改正。
交付阶段
交付阶段即项目的线上发布,我个人认为下面2个文档是很有必要的。
使用手册:见文知意,使用手册的最大作用是帮助用户可以快速熟悉并使用起来。当然还有一个作用,避免用户没得看而导致不断询问你各种问题,你可以甩给他使用手册,培养他学习使用的能力,降低自己的对线压力。
接入文档:因为是内部的技术项目,部分功能需要业务或者用户接入或者做一些配置上的变更。接入文档作用是赋能用户去做变更,而不是项目的技术同学去帮他们做变更,这也是节省资源的一种方式。
附:相关工具
项目wiki:飞书文档
原型图设计:墨刀
架构图设计:ProcessOn
接口管理工具:Swagger
这篇文章主要内容是介绍技术项目中比较重要的文档结构,以及对部分文档的作用做一个简单的说明,仅供参考。
后续我会和大家聊聊,技术项目落地交付以及交付质量的一些事情,敬请期待。
软件工程02组软件工程组队项目——课程管理小助手数据库设计文档
一、引言
1.1编写目的
数据库的表结构设计是整个项目开发中一个非常重要的环节,一个良好的数据库设计,可以提高开发效率,方便系统维护,并且为以后项目功能的扩展留下余地。我们通过书写这份文档说明,从各方面进行学生课程管理小助手系统的数据库设计规划,用它指导该系统在数据库各方面的内容,为系统开发的程序员、系统分析员提供基准文档。我们也希望通过写数据设计说明书,规范数据名称、数据范围、数据代码等。这份文档是项目小组共同作战的基础,有了开发规范、程序模块之间和项目成员之间的接口规则、数据方式,大家就有了共同的工作语言、共同的工作平台,使整个软件开发工作可以协调有序地进行。
1.2编写背景
1)待开发系统的名称:基于Windows的课程管理小助手系统;
2)本项目的任务提出者:老师引导下同学们共同讨论的结果;
3)开发者:柴增豪,刘硕,何祎君,潘恋军,张嘉熙,朱杰
4)用户:在校大学生、老师等
二、外部设计
2.1标识符和状态
联系用途,详细说明用于唯一地标识该数据库的代码、名称或标识符,附加的描述性信息亦要给出。如果该数据库属于尚在实验中、尚在测试中或是暂时使用的,则要说明这一特点及其有效时间范围。
2.2使用它的程序
课程管理小助手
2.3本系统的开发环境为
数据库:My sql 5.7,
编译器:visual studio编译器,
操作系统:Microsoft Windows 10,
辅助软件:Photoshop等
本项目用到的数据项:在名称,范围,类型等方面的约定见数据字典。
2.4支持软件
My sql 5.7,Vs2015编译器, windows 10操作系统,Power Designer12。
三、结构设计
3.1概念结构设计
清楚正确地表述本数据库反映的数据形式和联系:
3.2逻辑结构设计
3.2.1 数据库设计规范
数据库命名规则:db_数据库名称,每个英文单词第一个字母大写;
表命名规则:表名称_Info,每个英文单词第一个字母大写;
字段命名规则:每个英文单词第一个字母大写;
字段时间格式:所有时间格式采用2008-12-20 23:23:02的形式
3.3物理结构设计
3.3.1 数据表设计
参看数据字典。
3.3.2数据存取方面的设计
对经常在查询中出现的关系的码建立索引;对经常进行连接操作的关系的码建立索引;
对于更新频率很高的关系模型,所以没有定义索引,比如学生用户,由于技术不成熟,我们就不讨论存储位置的设计了。
四、功能数据需求
1.管理员基本信息的输入,包括用户名、密码;
2.教师用户信息的输入,包括用户名、密码、姓名、性别、年龄、开设的课程等;
3.学生用户基本信息的输入,包括用户名、密码、姓名、性别、年龄、学号、成绩、参与的课程等;
4.用户基本信息的查询、修改,包括姓名、性别等;
5.课程信息的输入,包括课程名称、类别、学时、上课时间、基本要求等;
6.课程信息的查询,包括课程名称、类别、学时、上课时间、基本要求等;
7.成绩信息的输入,包括学生姓名,考生学号,考试科目,成绩;
8.成绩信息的查询,包括学生姓名,考试科目,成绩;
9.管理员管理,包括创建学生、教师用户信息,删除和修改用户信息他。添加、修改和删除课程信息;
五、运用设计
4.1数据字典设计
4.1.1.管理员表格
表1 管理员表格
列名 |
数据类型 |
允许空 |
默认值 |
备注 |
Manname |
VARCHAR |
N |
|
用户名 |
Manpasswd |
VARCHAR |
N |
|
密码 |
Role |
VARCHAR |
N |
|
角色 |
4.1.2.教师表格
表2 教师表格
列名 |
数据类型 |
允许空 |
默认值 |
备注 |
Tchname |
VARCHAR |
N |
|
用户名 |
Tchpasswd |
VARCHAR |
N |
|
密码 |
Role |
VARCHAR |
N |
|
角色 |
Tchsign |
VARCHAR |
N |
|
编号 |
Tchclass |
VARCHAR |
N |
|
课程 |
Tchsex |
VARCHAR |
N |
|
性别 |
Tchborn |
VARCHAR |
N |
|
出生年月 |
Tchhometown |
VARCHAR |
Y |
|
家乡 |
4.1.3.学生表格
表3 学生表格
列名 |
数据类型 |
允许空 |
默认值 |
备注 |
stuname |
VARCHAR |
N |
|
用户名 |
stupasswd |
VARCHAR |
N |
|
密码 |
Role |
VARCHAR |
N |
|
角色 |
stuxuehao |
VARCHAR |
N |
|
学号 |
Stugrade |
VARCHAR |
Y |
|
成绩 |
Stumajor |
VARCHAR |
N |
|
参加的课程 |
Stusex |
VARCHAR |
N |
|
性别 |
Stuborn |
VARCHAR |
N |
|
出生年月 |
Stuhometown |
VARCHAR |
Y |
|
家乡 |
4.2数据结构设计
表4 数据结构
数据结构名 |
属性 |
管理员 |
用户名,密码和角色 |
教师 |
用户名,密码、角色、编号、开设的课程、性别、出生年月、家乡 |
学生 |
用户名,密码、角色、学号、成绩、参加的课程、性别、出生年月、家乡 |
4.3安全保密设计
数据库作为管理系统的基础,通常保存着重要的商店经营信息和客户信息。由于涉及到财务管理,数据的完整性和安全性显得尤为重要。系统中的数据一旦丢失,将需要很长时间进行恢复,有时甚至使信息系统不得不从系统初始化阶段重新开始运行。每天进行数据备份是保障系统安全的重要手段。数据备份需要严格按照事先制定的备份与故障恢复策略进行,并落实备份登记和检查措施。另外,系统设置用户的标识以鉴定是否是合法用户,并要求合法用户设置其密码,保证用户身份不被盗用;系统对不同的数据设置不同的访问级别,限制访问用户可查询的处理数据类别和内容;系统对不同用户设置不同的权限,区分不同的用户,如区分店长和店员。具体的系统配置应当根据系统实际运行情况做进一步的调整。
以上是关于如何设计良好的技术项目文档结构的主要内容,如果未能解决你的问题,请参考以下文章