V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
tctc4869
V2EX  ›  程序员

用户需求确定之后,如何编写软件应用开发中基于理论性描述的开发文档?

  •  
  •   tctc4869 · 2021-02-10 09:01:50 +08:00 · 1518 次点击
    这是一个创建于 1142 天前的主题,其中的信息可能已经有所发展或是发生改变。

    开发一个软件应用,假设初步确定了用户需求之后,要编写软件开发的文档,领导要求至少必须得写软件后端的理论性描述开发方面的文档。

    领导要求,理论性描述开发方面的文档的内容描述中,有一个要求让我很困扰,就是至少不能提及比较具体的开发内容,例如文档中主要描述的部分不能提及下列内容

    ( 1 )具体使用的开发语言,

    ( 2 )具体使用的开发工具,

    ( 3 )使用了什么通信传输协议( Http,tcp,udp ),

    ( 4 )使用了什么数据库(可以使用数据库这个词指代数据存储,但是不能提及是用了什么类型的数据库,是文档类型,还是关系类型,还是时序类型,也不能提及具体使用了哪个数据库产品)

    总而言之,该类文档注是那种注重于理论性、逻辑方面内容的描述。不能提及开发中比较具体的内容描述。

    那么我想问一下各位,按照这样的要求,编写这类文档内容,可以有哪些描述?

    既然不能提及具体的开发内容,那我想到的是三个理论性的描述方式

    ( 1 )理论性描述的应用架构结构图

    ( 2 )抽象所需要的业务实体,以及业务实体上所需要的关系关联

    ( 3 )预先设想并罗列可能需要的后端接口 API,至少写出必须提交的参数,请求完成响应的内容,需要哪些认证,以及 API 接口的详细描述说明

    假设要做的是学生选课系统。

    ( 1 )根据用户需求中的功能描述,绘制出理论性描述的应用架构结构图。

    ( 2 )确定业务上所需要的实体,可以确定至少业务实体有学生实体,教课实体。以及根据业务确定这 2 个实体之间所需要的关联关系

    ( 3 )罗列后端中可能需要的后端接口 Api,预先定义学生和教课的可能需要后端 API 接口。

    除了我所设想的,各位还知道这类开发文档的内容描述,还有哪些比较好的理论性的描述方式?

    9 条回复    2021-02-10 14:41:17 +08:00
    hxndg
        1
    hxndg  
       2021-02-10 09:43:08 +08:00 via Android
    找本操作系统里面的调度,或者看看深入理解 linux 架构里的 lru 就明白了。
    jones2000
        2
    jones2000  
       2021-02-10 13:07:09 +08:00
    不涉及具体内容, 哪不就是画大饼嘛, 使劲吹, 什么技术新就写用什么技术. 网上一大把, 拼一起就可以了.

    学生选课系统
    区块链数据存储.
    AI 自动选课.
    VR 虚拟课堂试听.
    人脸识别自动登录,
    微服务等等 .........
    imn1
        3
    imn1  
       2021-02-10 13:15:01 +08:00
    你最好问一下领导是给谁看的
    看领导这么说,很笼统的文档描述,应该是给客户看的,就是能让客户信任,不是乱开发而且是自主开发,但又不能太详细让客户可以自行(或者找别家)开发,这个跟一般开发文档不同

    软件文档其实有多份的
    开发的架构文档,注重原理和各模块的数据如何进出
    开发的过程文档,注重版本更替,及更替的原因( Bug 、功能变化等等)
    以及用户文档(说明和使用手册分开的话更多)

    公司内部保存的文档,不太可能不写具体的使用模块是什么,后续开发的人看会很混乱,所以更像是给客户看的
    如果确实是给客户看的,就按着“能看清原理,但不能照着文档自己开发”这个需求写
    Kirsk
        4
    Kirsk  
       2021-02-10 13:52:08 +08:00 via Android
    项目概要文档 描述项目整体技术边界
    tctc4869
        5
    tctc4869  
    OP
       2021-02-10 13:57:48 +08:00
    @imn1 “但又不能太详细让客户可以自行(或者找别家)开发”,重要的不是具体用了什么来开发,而是业务逻辑吧?
    tctc4869
        6
    tctc4869  
    OP
       2021-02-10 14:12:37 +08:00
    @imn1 会有写具体开发应用的开发文档,但是跟基于理论性描述的开发文档是分开的
    imn1
        7
    imn1  
       2021-02-10 14:15:52 +08:00
    @tctc4869 #5
    那就看开发者的水平了,我是看着深度学习的算法原理也写不出来的,只会用

    其实就是增加客户的开发成本
    洗衣机的原理简单吧,但如果没写电机的型号,皮带的材质长度等等参数,洗衣桶的承载容量等等,你 DIY 一个洗衣机就要每个部件自己试,跟从头开发差不多
    我的意思就是这样,写一些虚的,但不是假的,能说清原理但造不出来
    看你把 API 都罗列出来,这不是给客户看的,给客户看的是,“发送 XX 数据到 XX”,就够了,怎么发送,协议是什么,不需要,对方的技术人员问到再说
    tctc4869
        8
    tctc4869  
    OP
       2021-02-10 14:20:04 +08:00
    @imn1 Kirsk 提到的项目概要文档?那种算是是么?或者该类文档有哪些约定俗称的专业称呼?
    imn1
        9
    imn1  
       2021-02-10 14:41:17 +08:00
    @tctc4869 #8
    概要文档就是项目的描述,只要项目不死,这个文档就有效存在,或者说版本变化不大
    但项目细节是会变的,例如最初可能 sqlite 就够了,发展到 mysql,到更大,那么用什么数据库就不需要写进概要文档
    概要文档着重 WHAT 、WHY 、WHEN(启动时间),WHERE 、WHO 、HOW 的部分比较简略

    专业称呼我也没留意,以前习惯叫 XX 项目概要,或 XX 项目概要方案、XX 项目说明书;如果给外人看的,就修改部分,变成介绍、宣传稿……

    你可以搜搜“项目文档分类”
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   982 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 21:59 · PVG 05:59 · LAX 14:59 · JFK 17:59
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.