hugh 的个人博客

关于技术团队文档建设的一些思考

前言

一个业务或技术团队,如果不考虑不可抗力因素导致的衰败和消失, 那它就会随着时间一步步发展和迭代, 人员也会不断的更新。如何更好的保障一个业务的持续维护,文档在其中起到了很大的作用

那么我们一般都会维护哪些文档呢?
毫无疑问,
新人文档:是大家基本都会有的文档, 这类文档用于新人快速项目技术和业务的重要入口
业务文档:一般包含了我们的业务需求文档或我们梳理的代码逻辑文档
技术文档:通常会包含技术方案、技术实践等

一般文档的维护会存在哪些问题

  • 缺乏重点
    如新人文档, 我看到过很多新人文档, 除了内容的确适合新人看之后,基本都缺乏新人引导的流程, 一般都是靠mentor或者自己问才能真正上手
  • 时效性差
    这一般体现在业务文档上, 由于业务上不断发展的, 业务文档一般都会存在时效性问题,如果只是做完追溯的需求文档还好,纯业务文档时效性差会上致命的!
  • 内容规范性不够
    由于文档一般都是组内或相关同学自发编写,如果没有足够的规范性约束,会出现很多低质的文档,反而对整体的文档的置信度起到了反作用
  • 命名规范性缺乏
    命名是最有效又最容易被忽略的一项,好的命名可以帮助我们快速查找和了解文档的内容

如何更好的维护团队的文档呢

  1. 目录建设

    目录是我们文档编写的基础, 同时好的目录结构,可以帮助大家规范文档的分类,也便于我们进行快速查找

- 团队
-- 团队 - 新手引导
-- 团队 - 业务文档
-- 团队 - 技术文档
-- 团队 - 技术分享
-- 团队 - 规档

如上, 我们按一定曾经划分目录,并保持命名的一致性, 虽然有一些冗余, 但是整体提高了可读性和舒适感,建议可以这样做

  1. 新手引导
    新手引导是很关键的一环, 我们期望这个目录可以给予新人明确的引导,通过这个目录直接可以对业务和技术又一定的了解
    这个部分应该需要包含一下的目录

    - 团队 - 新手引导
    -- 团队 - 新手引导 - 快速了解业务
    --- 团队 - 新手引导 - 业务 - 介绍
    --- 团队 - 新手引导 - 业务 - 如何快速启动项目
    -- 团队 - 新手引导 - 开发流程
    --- 团队 - 新手引导 - 开发 - 需求评审
    --- 团队 - 新手引导 - 开发 - 技术评审
    --- 团队 - 新手引导 - 开发 - 编码
    --- 团队 - 新手引导 - 开发 - git wf
    --- 团队 - 新手引导 - 开发 - cr
    --- 团队 - 新手引导 - 开发 - 测试
    --- 团队 - 新手引导 - 开发 - 上线
    --- 团队 - 新手引导 - 开发 - 监控
    

    通过步步规划, 新手只需要通过逐步阅读文档,就可以轻松了解当前团队的业务和工作流程

  2. 业务文档
    业务文档最好编写也最难维护, 我们还是需要建立一套合适的机制来维护业务,常用的方式如下

    • 代码即文档
    • 系统管理业务
  3. 技术文档
    技术文档是我们技术同学比较关心的, 一般用于存放技术方案,正对技术方案,我们就需要有相关的方案模板, 避免大家自由发挥

    那技术方案一般包含哪些模块呢

    • 需求描述和相关文档
    • 技术实现的关键点
    • 编码注意点checklist: 该项是我们要在系统维护过程中不断沉淀的,我们通过该checklist,来体现技术实现者关注相关的内容,避开易错的问题
    • 需求点自测case: 该项是督促需求实现者,要完成需求的自测
  4. 其他
    其他目录基本参考以上几类即可


标题:关于技术团队文档建设的一些思考
作者:hugh524
地址:https://blog.uproject.cn/articles/2021/08/08/1628436794251.html