码迷,mamicode.com
首页 > 其他好文 > 详细

基于 README 的文档管理

时间:2021-06-13 09:57:10      阅读:0      评论:0      收藏:0      [点我收藏+]

标签:apache   rect   格式   答案   block   about   规范   需求   with   

什么是 readme§

A readme (or read me) file contains information about other files in a directory or archive and is very commonly distributed with computer software.

为什么要在仓库中写文档§

  • 文档和代码在一起,方便查看
  • 文档和代码版本一致
  • 使用 markdown 格式的 README 文档可以在 GitHub 中直接查看
  • 可以在 vim 中查看
  • README 已经能(并且能更好的)满足大部分需求

markdown 规则§

推荐遵守此规则:

Markdown 规范 + GitHub Flavored Markdown

应该叫什么名字§

建议叫 README.md

而不是 readme.md 或 README.markdown

愿景§

尽量替代掉「使用 wiki 或 website 管理文档」(或者 website 是通过 readme 文档生成的,do not repeat yourself)

readme 内容§

一个好的 README 需要包含哪些内容?以下是 stackoverflow 给出的答案

  • 此项目的标题和包含的子模块
  • 对项目和子模块的描述
  • 一个简短的例子告诉读者如何使用
  • LICENSE
  • 在哪儿可以找到文档
  • 怎么安装,配置,运行此程序
  • 在哪儿可以找到最新代码
  • 作者
  • 如何提交 bug,提建议,加入讨论组
  • 其他联系方式(email,website)
  • 简短的历史介绍
  • 法律声明

我推荐包含以下内容:

  • 标题
  • 描述
  • 使用方式
  • [ optional ] 链接(npm,website,wiki,git repo)
  • [ optional ] 作者(联系方式)
  • [ optional ] 测试脚本
  • [ optional ] demo 页
  • [ optional ] 代码说明,设计模式,维护须知
  • [ optional ] 更新历史
  • [ optional ] Troubleshooting
  • [ optional ] Todo

Links§

本文转自 https://blog.xcatliu.com/posts/use_readme_to_manage_your_docs.html,如有侵权,请联系删除。

基于 README 的文档管理

标签:apache   rect   格式   答案   block   about   规范   需求   with   

原文地址:https://www.cnblogs.com/hustshu/p/14877916.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!