📒 项目说明怎么写 - Readme 的自我修养
!本篇文章过于久远，其中观点和内容可能已经不准确，请见谅!~
想分享的是自己在团队内推行的一个项目说明，尤其是多项目切换和多人协作的工作环境。
项目的声明周期包括初始化、开发、迭代、部署、交接等，一个维护良好的项目的这些流程不可能随意混乱。在 git 仓库托管大部分项目的背景下，readme 一般作为一个 work board 角色，标记每个重要的说明。从我目前的工作中，聊聊怎么才能较好的维护一份产品文档，不至于快速上手两年前的老旧服务，不至于离职一周搞不定交接。
一个产品文档的详细程度与复杂程度、涉及人数、重要性、相关联度有关系，简单的一个项目也不需要长篇累牍的说个没完，实现和逻辑都放到代码里，文档是作为一个说明书存在。
GitHub 上的开源项目根据不同的用途，一般有是什么和怎么用的分类，包括简单介绍、Features、Usage(Get Started)、Demo、ChangeLog、License
其中 get started 有的是怎么用接口，有的是怎么在此基础开发。当然我们自己的项目和这些开放的项目不同，但是也是能借鉴下。
我们写这个文档的目的其实说白了是面向离职编程，别人甚至自己看到这个文档都不需要指导就能很好的交接，当然这个东西是让负责协作的小伙伴、后续维护的小伙伴、部署到线上的小伙伴都能舒心的，不多的文字就能省下很多口舌之争。
具体要介绍的东西有：
- 项目是干嘛的
- 为什么开这个项目
- 项目参考的具体文档和需求
- 怎么才能让项目安全跑起来、停下来
- 需要依赖哪些其他服务
- 怎么才能本地调试
- 项目的基本目录和架构说明
- 注意事项和一般异常说明
做到上面的条目，基本上也能大致明白项目的整体了。
- 开发环境、依赖准备
- 开发启动、预览、调试步骤
- 技术选型
- 核心代码功能
- 项目目录结构和重点文件说明
- 开发注意事项
上面这些详细的从零开始开发步骤，方便自己迁移、再维护，方便别人接手项目。尤其是依赖很多前期依赖准备的开发模式，比如一个核心功能，需要本地额外启动多个 mock 数据库、mock 接口、配置调试环境等，这个时候一个 command list 真的会将准备时间从一个小时还不知道有没有完整缩减到 5 分钟准备完毕。（PS：其实如果日常开发需要这么些配套 server 启动，需要手动开发一个命令行之类的工具作为脚手架来缩减到 1 分钟时间。）
项目文档如果脱离了团队的环境也没什么意义，所以团队怎么维护项目的，老项目怎么快速上手，每个项目怎么部署、开发都是有一个通用技术栈的，并不存在一个标准的模版文档，尤其是项目快速迭代，文档的维护很多时候也是力不从心。尤其项目赶工、团队很小、技术栈简单的情况，文档也并不是非要事无巨细。
亲身体会一个小公司，从简单口头交接即可，到画到白板上才能说清全部服务，最后全都标准化到文档的一个过程。
下面是小团队之间，内部项目较多的情况下的一个示例：
----# 项目名称> 项目功能简介。（说明：用精简的文字描述本项目目前版本、主要功能、部署位置、目前维护人员等）[TOC] （说明：文档的目录。较长的文档最好增加文档索引目录）----## 1. 背景### 1.1 项目的开发背景xx### 1.2 需要解决的问题xx### 1.3 产品文档位置(GIT)xx### 1.4 主要参考接口文档位置(GIT)xx（以上选写）----## 2. 安装/部署说明机器类型、服务类型、工作模式（从干净的服务器机器，到能正常运行服务的全部环境安装和配置，包括代码更新、启动停止、日志保存）### 2.1 安装机器xx### 2.2 环境准备xx### 2.3 代码部署xx### 2.4 服务启动/停止/自启动xx### 2.5 注意事项/tipsxx----## 3. 开发说明### 3.1 初始化代码仓库git clone gitlaburl libname### 3.2 技术选型使用了什么框架，架构等### 3.3 本地环境（从干净的开发机器，到能正常进行开发的全部环境安装和配置，方便工作转移交接）软件/相关配置/开发预览其他说明### 3.4 建议开发步骤在那个文件夹下执行什么命令，到什么页面预览效果；开发什么工具能方便开发----## 4. 本地目录目录结构介绍## 5. 其他
感谢您的阅读，本文由 Ubug 版权所有。如若转载，请注明出处：Ubug（https://ubug.io/blog/project-readme）
