linux_china技术雷达linux_china技术雷达

Good README

git
采用

README是一个项目的门面，是项目的第一印象，在项目中起着非常重要的作用。 一个好的README可以帮助他人更好地了解项目，更好地参与项目，更好地维护项目，更好地使用项目，这个是必不可少的。 如何编写一个好的README.md一直是一个问题，很多人都不知道如何写，或者写的很差，一些项目干脆没有。

这里提供一个模板，希望能帮助到大家。

  1. Context: 项目标题，背景介绍，为何要这么做，会有什么意义，包括业务背景、技术背景等等。
  2. Function Overview: 功能一览，这里做好提供图示和功能列表，让别人一目了然
  3. Quality Attributes: 质量/品控要求，如果性能、响应时间、可用性、可扩展性、可维护性等有特殊要求。
  4. Constraints: 限制和约束，如技术限制、时间限制、人员限制等，当前做不到哪些功能或者事情。
  5. Principles：行为准则，就是你必须要这么做，如日志处理、metrcis，监控接入等，还包括你不能做什么，如不能重复造轮子，抢占他人底盘。安全的一些原则，都在这里进行说明，必须https，不能明文密码保存等等。
  6. Software Architecture：软件架构，这里主要是设计的方法论，如微服务架构、领域驱动设计、事件驱动、六边形设计、CQRS(读写分离) 等，这里一定要有，即便做的差也没有关系，让别人知道你是怎么想的，这样别人才能更好的和你沟通，否则别人只能猜测你的想法，这样会导致很多问题。
  7. Code：代码，要说明项目的代码组织结构，如Maven的multi module说明，package如何组织。如果有必要请说明一下你的技术栈和核心库的选择。
  8. Data：主要涵盖数据库、NoSQL、消息等，可能还会涉及OSS、CDN等
  9. Infrastructure Architecture: 基础设施架构，如网络，存储，计算资源等
  10. Deployment: 部署结构，如基于VM、K8S还是Serverless平台
  11. Operation and Support：运维支持，Spring Boot Actuator和Metrics是重要环节，如果可能的话，提供相关的运维脚本，说明你已经考虑这些问题啦。
  12. Development Environment：开发环境，如IDE，工具，.env设置，docker-compose.yaml等。
  13. Decision Log: 决策日志，当有一些和主流做法不一样时，一定要进行决策说明，不然别人一定会问，而且会问很多次，每次都和祥林嫂一样去解释。
  14. References: 参考，相关的站点，文章文档等，方便自己和他人查阅。

README & Friends