我们应该如何书写README及文档

我们应该如何书写README及文档

---

项目背景：

一份好的文档可以减少很多沟通上的问题，这在团队开发中至关重要。能够写出好文档的人，我相信在团队中应该会更加受欢迎。那么一份好文档应该有哪些要素呢？

• 风格统一：让经常阅读你文档的人能够快速的找到自己想要的内容，能快速的明白你想表达的内容。
• 要素齐备：总有一个内容是你想要的。
• 简明扼要：能够一句话说出你想表达的，说明你才对你的项目真正了解。当然有些东西没法精简。

上手指南

---

ok 现在我们有了一个基本概念了，那么怎么上手呢。

1. 首先准备一份你个人觉得ok的文档规范，例如下面这个

   • 项目背景

   • 上手指南

     • 安装要求（指明项目的依赖环境）
     • 安装步骤（可有可无，如果有一些特别恶心的配置还是建议写一下）

   • 测试

     • 检查依赖环境是否正常的测试
     • 如果此项目是针对什么具体业务的话提供一些基本测试用例还是必要的可以让别人快速明白这个是干嘛的

   • 部署

     • 如果你的项目是可以上线的,那么如何配置部署文件也是一个很重要的内容.因为有些平台不用不知道，谁用谁知道（一用根本用不来）ヽ(ﾟ∀ﾟ*)ﾉ━━━ｩ♪

   • 框架或者技术选型

     • 方便快速识别是敌是友

   • 贡献者

     • 毕竟写文档肯定都是为了交友啊(参考某G开头的大型同性交友网站)
     • 混个脸熟以后好搞事情
     • 对于大家的参与表示精神上的鼓励(ε=ε=ε=┏(゜ロ゜;)┛)

   • 版本控制

     • 告知使用了什么版本控制系统

   • 作者

     • 让大家来膜拜你 (大雾)

   • 版权说明:

     • 仅针对开源项目,内部开发没有必要

   • 鸣谢:

     • 做一个有礼貌的人,用了别人的东西就帮别人打打广告.

测试

---

你看到这篇文章的时候说明已经通过测试了?

部署

---

本文部署在我的博客上,你要部署就自己建一个博客,想怎么部署都行.?

框架

---

readme.md 不知道你见过没有.?

贡献者

---

感谢以下贡献者

我自己?

版本控制

---

version: 1.0.0

作者

---

我自己?

版权说明

---

本文版权归我所有,你要有啥事,就联系我.?

鸣谢

---

感谢各位对我的支持,看到这里.

本文参考了purpleBooth的README-template.md感谢该作者的共享.