本文次要为须要编写软件设计/开发文档的读者提供一些教训和倡议。浏览前提理解 Markdown 语法理解 Typora、Sublime Text 或 VS Code 等不便编辑 Markdown 的编辑器面向读者须要编写产品/性能形容文档的产品经理、项目经理须要针对待开发性能编写根本设计、具体设计的软件工程师1. 软件和文档格局抉择一般来说,软件开发相干的设计文档大多都具备以下特点:不须要特地花哨的款式常常须要批改除 UI 设计外,以纯文本为主根本构造、格局大体雷同常常有代码、数据呈现,须要不便复制因而,个别倡议此类文档应用纯文本的 Markdown 格局编写。Markdown 应用一些简略的标记语法,即可展示最罕用的题目、列表、重点、援用、代码块、链接等性能。前期也能不便地导出为 HTML、PDF 等格局。无关 Markdown 语法可参考:https://www.runoob.com/markdo... 设计文档的根本构造编写设计文档时,必须以「公司新人」的视角去编写,不能对读者实现所理解的内容做任何假如。因而,一份设计文档,一般来说至多须要蕴含以下几块内容:“一句话形容”的题目目录业务流程数据定义2.1 「一句话形容」的题目不要间接应用「文档」、「设计文档」作为文件名或题目。文件名或题目最好应用「一句话形容」,如:观测云新 Event 数据结构及解决逻辑设计观测云云关联解决逻辑设计这样,一来不容易有文件重名问题,二来读者可能在不关上文件的状况下,大抵理解文档内容。2.2 目录任何文档都要增加目录,这样能够不便读者在首次浏览时理解文档大抵内容,也能不便疾速查阅、跳转到特定内容。应用 Typora 能够抉择「段落 - 内容目录」插入目录应用 Sublime Text、VS Code 能够应用 MarkdownTOC 等插件生成目录留神:不同软件的目录实现形式不同,相互之间可能不兼容2.3 业务流程任何设计文档都要对业务流程进行形容,具体写明「用户做了什么操作,零碎进行了什么解决,最初产生了什么」。对于简略的业务流程,能够间接应用列表进行形容,如:用户输出用户名、明码,点击登录零碎依据输出内容查找匹配的用户匹配胜利,跳转到 Dashboard 页面匹配失败,提醒「用户名或明码谬误」对于简单的业务流程,能够应用流程图形式形容,如:提醒:流程图能够应用 ASCII Art、业余流程图工具、PowerPoint、Keynote 等软件进行绘制2.4 数据定义业务流程中产生的业务实体,必须明确所有的字段、字段类型、取值范畴、数据起源等信息。假如存在业务实体「课程」,数据定义表格如下:留神:表格中阐明不宜过长,对于某些须要简单阐明的字段,该当为其独自开设上级题目进行详细描述应用表格展现字段列表,构造更为清晰,对阅读者累赘也更低。此外,在因为在编写时也不容易脱漏字段的某些形容。对于 JSON 数据,也能够间接应用 JSON 格局展示,如:{
// [必须] 课程编号,全局惟一"code": "CLASS-001",// [必须] 课程名称"name": "语文 1",// [必须] 课程类型,可选值:理科=`liberal`、文科=`science`"type": "liberal",// [必须] 地位数量,取值范畴:`0 ~ 100`"seatCount": 100,// [必须] 课程创建人 ID。创立时主动填入"userId": "user-001",// [必须] 老师列表"teachers": [ { // [必须] 老师的用户 ID "userId": "user-002", // [必须] 老师职位,可选值:主讲人=`speaker`、助教=`assistant` "position": "speaker" }, { "userId": "user-003", "position": "assistant" }],// 课程标签,元素为 String"tags": [ "根底", "必修", "特级教师主讲" ],// 额定信息"extraInfo": { // 是否须要自带计算机 "computerRequired": false, // 是否蕴含户外活动 "outdoorActivityIncluded": true}}留神:应用 JSON 格局展示时,该当整顿为容易浏览的缩进格局举荐优先应用表格形式形容,JSON 形式次之,同时提供表格和 JSON 形式则为最佳!3. 更简单的设计文档对于小型零碎、单个功能模块的设计文档,提供上述 4 个根本内容根本能够满足需要。如果是针对整个零碎的形容,或者多个、简单功能模块的设计文档,那么就有必要减少更多的内容来进行阐明。3.1 拆分大型零碎的设计文档对于大型零碎的设计文档,该当将文档划分为层级:根本设计:形容零碎整体架构,但不必波及到具体性能外部的细节具体设计:形容具体功能模块、具体性能所波及的业务实体、解决流程、字段定义等3.2 概念解释文档中呈现的的概念、业务实体须要明确的定义,防止误会。如:课程class:指的是蕴含课件、教材的「课程内容」,如:「云计算入门」场次activity:指的是某一个课程在特定工夫地点进行的流动,如:「云计算入门 2021 年上海第一场」并配合示例示例进行阐明。如:后盾管理员创立并录入「云计算入门」课程(这里操作的是「课程class」)讲师依据排课表,抉择「云计算入门」开课,并指定开课时间(这里操作的是「场次activity」)学生依据曾经开设的课程,抉择城市和工夫进行报名(这里操作的是「场次activity」)优于疫情,勾销了 2020 年所有的培训(这里操作的是「场次activity」)云计算曾经深入人心,没有持续开课的必要,「云计算入门」下架(这里操作的是「课程class」)3.3 架构图无论是零碎整体设计,还是单个功能模块的设计,都能够附带架构图不便读者了解。如:DataFlux Func 的架构图如:DataFlux Func 中「订阅器」的架构图3.4 我的项目文件目录曾经成型的我的项目,一方面为了让新人可能疾速把握我的项目整体状况,另一方面为了标准后续开发工作,能够增加我的项目文件目录进行阐明。如:DataFlux Func 我的项目目录阐明3.5 参考链接对于文档中呈现的关联、参考文档,该当列举进去,不便疾速参考。如:阿里云 ECS 列表 API 参考文档:https://help.aliyun.com/docum...腾讯云 CVM 列表 API 参考文档:https://cloud.tencent.com/doc... EC2 列表 API 参考文档:https://boto3.amazonaws.com/v... 正当应用格局正当应用格局,能够帮忙读者更快地理解内容,升高浏览累赘。4.1 题目为每个题目加上分级编号,会使得目录更清晰,同时也能不便读者随时确定以后的浏览地位。如本文应用了1.、1.1、1.1.1形式编排大小标题但须要留神的是,题目层级不易过深,个别以不超过 4 层为佳。最小一层的题目能够思考不增加分级编号,如:1. 云计算概述
...