本文仅仅是一个角度，可能还有的就是《中间件产品化之系统设计》，先做一个记录吧。
一般软件开发会遇到以下问题，为了解决这些问题，我们需要做好基础软件的产品化的周边管理。
- 开发离职。一个开发人员离职后，会留下凌乱的文档，这些文档不规范，对后续维护并不是很友好。
- 新人入职。新同事入职公司，对一个项目不熟悉，想要快速上手，不仅有时间成本，也有人力成本。
- 公司和团队其他人想学习或者参与开发。
- 运维部署项目遇到各种问题，运维不好排查。
- 对外开源。想要开源，发现根本无法做到，一个项目，部署N个节点。没有任何文档。甚至有些节点可能都已经宕机了，但是不影响产品使用。等等问题
所有好的基础软件需要完善产品化。对于一个软件产品，包括代码，文档，资源等的管理。一般软件自身从人都角度看可以有2个角度，对外和对内。比如说github托管的代码，官方网址中的文档都是对外的。而软件内部对自己开发者也肯定有一些资源，这些便是对内的。而从软件自身角度讲，一个软件产品，既要做到独立的产品化，也要和公司平台进行整合。这是2个角度。好的做法就是，既能独立产品化，又能轻易和公司基础平台进行整合。整合包括界面控制台整合，用户权限整合，访问认证，数据等等。
先说对外
对外代码。
一个项目，如果设计到多个节点。可以拆分成多个project，比如说前端页面，后端服务可以是2个或者1个项目。再比如说一个项目有多个节点，每个节点都是一个project。代码管理中需要做到聚合。也就是一个项目不能放在2个地方。比如放在公司gitlab或者外部哪里。最好是一个地址，能够表述一个完整对项目涉及到到所有代码。一般代码中，不可以出现文档类东西。因为文档模块一定是有到，如果在代码中放一个文档目录，则会使得资料不聚集，而且也不能出现bak，temp，docs，这种目录，随着时间周期的拖延，这些东西很快会变成“要不要删掉”的矛盾中。
对外文档
文档一定是有的，用户讲述一个项目。好的文档管理，以人为对象(不同的参与者可能关心的事情是不一样的)，既要简单明了，又要深入细致。
1 面向用户的文档（用户文档面向的是使用者，用户文档一般是最重要的文档）
- 产品介绍。做的东西再好，没人用，就没有任何价值。如果让别人知道你的产品，就需要有产品介绍。产品介绍一般需要把，是什么？有什么优点？有什么缺点？解决了什么问题？为什么要用我不用其他的。讲到。
- 必须有第一个入门实例。这个第一个例子需要做到什么程度，那就是用户完全不懂的情况下可以跑一个例子出来。如果一个人不懂java，不懂公司资源流程，不知道公司系统地址情况下，可以根据文档写一个例子。那就说明文档写的够好。肯定是足够完整全。好的文档不仅有步骤，还需要包括步骤说明。
- 功能介绍。软件有很多功能，每个功能都需要在用户文档中说明。做到有图有真相，控制台的截图，代码例子，都需要做上去。功能还需要以点为核心。以功能边界为单位。
- 版本发布说明(release-notes)。软件每次升级都会有版本号，比如1.2.4这样。每个版本发布需要有完整的升级说明。
- API介绍。api介绍，一般也可以有，我比较推崇的做法是，正确的使用注释。
- 原理介绍。很多使用者非常关心软件的原理，这个是多年工作积攒的经验。很多人在使用你的中间件的时候，如果对原理一无所知，有时候也会有错误的用法，而错误的用户可能会导致维护成本，或者系统风险。
- 视频教程。视频跟文档相比，更容易理解，更容易记忆。阿里云的很多产品也在做视频教程。所以视频教程也是我比较推崇的一种介绍产品的方式。
2 面向开发者文档
- 源码介绍。源代码的地址在哪里？源代码的所有涉及到的点必须讲到。
- 源码构建。开发者拿到代码后，如何编译，如何导入到开发工具，必须涉及到。好到文档可能会把导入到eclipse，idea等工具都统统讲到。然后跑一个例子看看。
- 开发规范和原则。好的软件可能会有很多约定。如果每个人按照自己的风格做，软件的发展会有失偏颇，但是如果真的遇到错误的点。比如说orm层框架觉得不好，想要替换，最好是有专门的改动版本统一改动。而不是新人只按照自己的做。
- 版本管理。每个公司对版本的约定是不一样的。这个也是需要文档说明。一般有大版本的整改，中等版本的大功能升级，小版本的小功能升级或者bug修复等等。
- 功能原理介绍。这个很像一些源码分析文章，通过代码介绍去讲解功能。
3 周边
- 博客。 一个好的软件，有用户，用户就会有五花八门到用法，这些东西都是可以作为实战博客记录下来的。
- 开发负责人。最后是可以留一些开发者的邮箱，让其他人可以联系都作者。
- 讨论群。qq群，微信群，叮叮群，不用多说。
- 论坛。其实我一直很排斥群聊技术，比较推崇论坛，而论坛比较好的方式是。置顶1，2，3的帖子把一些核心的概念，笔记，讨论记录下来。非置顶的可以让别人去看，去搜，一些垃圾讨论直接删帖即可。
- 运维建议。运维建议包括，节点，服务器配置，部署架构，数据架构，jvm参数就是自己实战中经过测试，线上使用后的一些环境信息，最好也可以给到外部用户。
再说对内
对内文档
1 工作任务相关
- 开发进度和人员管理的负责模块。okr，kpi等等。(对下属)
- 季度的整体任务节点。有的公司是喜欢以月为单位，有的以季度为单位。(对上级)
- 业务方接入流程。接入该产品的流程，方法，demo等等。(对同事)
2 项目相关
- 需求池。 其他部门对软件对诉求，产品规划，个人独立想法。
- 架构设计文档，方案。
- 性能压测和优化记录。
- 产品问题复盘。遇到到一些风险点，bug，疑惑问题，核心都是需要记录下来的。
3 现状相关
- 部署现状。环境和地址，及其QPS，服务器配置，服务器资源，每日访问量等
- 使用范围。公司有哪些团队，哪些人在使用，哪些项目在使用，有哪些版本在使用。
4 PPT
- 一般无论是团队内部，还是公司内部，还是社会，都是需要对外分享到，所以ppt也是要准备的。ppt相关略。
5 个人目录
- 很多人喜欢记录云笔记，这样是个好习惯，但是如果是纯工作，而不是隐私到话，专门在统一项目中给大家按照 “/中间件产品/消息通讯/个人目录/张三” 这样记录自己想法，可以让别人看到也是不错的。
网友评论