如何在开发项目的时候写出标准的README文件?

为什么要写这篇博客?

关于README的编写,这个也十分的重要,如果你觉得只是随便写写,那么你就错了;编写这部分也是相当的重要的。工欲善其事,必先利其器。故而我们在这里介绍一款编译器MarkDown编译器。

对于大神来说,可能这不算什么,但对于小白的我们这个还是十分的有用的;其语法比较简单,在几分钟之内就能够很轻松的学会这个软件。

在这个部分我大致分为两个部分向大家进行介绍:

关于完整的README的内容

关于README的内容,我觉得每个项目里面都应该有这么一个文件,目的是为了能简要描述该项目的信息,让读者快速了解这个项目。

一、它需要说一下几个事项

  1. 软件定位,软件的基本功能
  2. 运行代码的方法:安装环境,启动命令
  3. 简要的使用说明
  4. 代码目录结构说明,更详细点可以说明软件的基本原理
  5. 常见问题说明

二、它包括一下几个内容

  1. 项目和所有子模块和库的名称(对于新用户,有时不同命名会导致混乱)。
  2. 对所有项目,和所有子模块和库的描述
  3. 如何使用 5-line code(如果是一个库)
  4. 版权和许可信息(或阅读许可证)
  5. 抓取文档指令
  6. 安装、配置和运行程序的指导
  7. 抓取最新代码和构建它们的说明(或快速概述和「阅读 Install」)
  8. 作者列表或「Read AUTHORS」
  9. 提交bug,功能要求,提交补丁,加入邮件列表,得到通知,或加入用户或开发开发区群的介绍
  10. 其他联系信息(电子邮件地址,网站,公司名称,地址等
  11. 一个简短的历史记录(更改,替换或者其他
  12. 法律声明

三、一个简单的范本(当然,我们前期写的话,不必要那么麻烦,就写几个简单的必要的东西,比如法律声明啊,联系记录啊等等,就不必要写)

DEMO
=========================== ###########环境依赖
node v0.10.28+
redIs ~ ###########部署步骤
1. 添加系统环境变量
export $PORTAL_VERSION="production" // production, test, dev 2. npm install //安装node运行环境 3. gulp build //前端编译 4. 启动两个配置(已forever为例)
eg: forever start app-service.js
forever start logger-service.js ###########目录结构描述
├── Readme.md // help
├── app // 应用
├── config // 配置
│ ├── default.json
│ ├── dev.json // 开发环境
│ ├── experiment.json // 实验
│ ├── index.js // 配置控制
│ ├── local.json // 本地
│ ├── production.json // 生产环境
│ └── test.json // 测试环境
├── data
├── doc // 文档
├── environment
├── gulpfile.js
├── locales
├── logger-service.js // 启动日志配置
├── node_modules
├── package.json
├── app-service.js // 启动应用配置
├── static // web静态资源加载
│ └── initjson
│ └── config.js // 提供给前端的配置
├── test
├── test-service.js
└── tools ###########V1.0.0 版本内容更新
1. 新功能 aaaaaaaaa
2. 新功能 bbbbbbbbb
3. 新功能 ccccccccc
4. 新功能 ddddddddd

  关于MarkDown

  具体语法参照这篇简书的文章MarkDown使用指南

  关于windows程序如何生成结构目录树

windows程序如何生成目录结构树?

 电脑中打开cmd

在cmd中进入要生成目录结构的目录

输入:tree /f > list.txt(目录结构输入成功,并保存为一个list.txt文件)

打开此文件,即可看到生成的目录结构树

关于README的内容的更多相关文章

  1. 如何为开发项目编写规范的README文件(windows),此文详解

    为什么要写这篇博客? 其实我是一个入坑已经半年的程序员,因为不是计算机专业,只能自己摸索,所以我深知博客的重要性.每次我的学习笔记啊,项目的,面试题啊,有的,只要有时间,我肯定上传上来,一方面自己可以 ...

  2. P4factory ReadMe Quickstart 安装p4factory

    操作系统: Ubuntu 14.04 前言 在之前,我直接从P4.org给的GitHub网址上下载了p4factory,但是在根据ReadMe的内容进行QuickStart的时候,发生了shell脚本 ...

  3. 视频转成在github的readme中展示项目的gif动图

    本文中涉及的FastStone Capture和FFmpeg两个软件的百度网盘链接: 链接:https://pan.baidu.com/s/1D5LO9Qmjl-vwJZfnbAloyQ 提取码:56 ...

  4. git中报错---fatal: pathspec 'readme.txt' did not match any files

    1.git安装 git官网下载最新版本,一键安装或custom install. 2.会弹出一个类似的命令窗口的东西,就说明Git安装成功. 3.安装完成后,还需要最后一步设置,在命令行输入如下--- ...

  5. 错误 error: The following untracked working tree files would be overwritten by merge:README.md

    问题类型 相信很多小伙伴在创建新的git仓库后,会选上添加README.md文件,开始我也没太在意,应该也没有什么问题. 但是当我通过git添加远程仓库,给这个仓库上传代码时,出现了如下问题:erro ...

  6. 如何为开发项目编写规范的README文件

    前言 了解一个项目,首先都是通过其Readme文件了解信息.如果你以为Readme文件都是随便写写的那你就错了.github,oschina git gitcafe的代码托管平台上的项目的Readme ...

  7. Github 新玩法 -- Profile ReadMe

    Github 新玩法 -- Profile ReadMe Intro 今天刷 Github 的时候偶然发现一个新的玩法,Github Profile ReadMe,可以在个人的 Profile 页面展 ...

  8. Github 个人首页的 README,这样玩儿~

    本文首发于 Ficow Shen's Blog,原文地址: Github 个人首页的 README,这样玩儿~. 内容概览 前言 创建仓库 修改 README 的内容 总结 前言 大家最近有没有发现这 ...

  9. 史上最详细git教程

    题外话 虽然这个标题很惊悚,不过还是把你骗进来了,哈哈-各位看官不要着急,耐心往下看 Git是什么 Git是目前世界上最先进的分布式版本控制系统. SVN与Git的最主要的区别 SVN是集中式版本控制 ...

随机推荐

  1. About Game Controllers

    [About Game Controllers] Game Controller(GC),框架从iOS 7和OS X v10.9开始加入,用于便捷使用控制器(手柄). Once discovered, ...

  2. 数据挖掘潜规则zz

    声明:本文指的是做数据挖掘这行,不是数据仓库 我干这行有几年了,见了很多人,干了很多公司,爆一爆这个行业的状况吧……让后来人有所了解,也让猎头挖人挖的有点方向,起码和candidates聊天的时候不至 ...

  3. 【转】Defunct进程 僵尸进程

    在测试基于 DirectFB+Gstreamer 的视频联播系统的一个 Demo 的时候,其中大量使用 system 调用的语句,例如在 menu 代码中的 system("./play&q ...

  4. WCF Service 配置文件注释(转)

    <?xml version="1.0" encoding="utf-8" ?> <configuration> <system.S ...

  5. 从Objective-C到Swift,你必须会的(一)#pragma mark

    在Objective-C里,为了让代码组织的有序也方便用control+6的快捷键在Xcode中查找,所以出现了一个大家都很熟悉的东东.这就是:#prama mark. #pragma mark  但 ...

  6. Appium之uiautomator定位元素

    元素定位方式有多种,Android也有自身独有的定位方式.下面就单独介绍其基于uiautomator定位元素的方法: 基本语法: driver.find_element_by_android_uiau ...

  7. Spring全局异常处理

    最近学习Spring时,认识到Spring异常处理的强大.之前处理工程异常,代码中最常见的就是try-catch-finally,有时一个try,多个catch,覆盖了核心业务逻辑: 1 try{ 2 ...

  8. [ThinkPHP] 比较标签 neq&nheq 与 PHP 中的 != 与 !== 出现的问题

    1. 模板 > 内置标签 > 比较标签 控制器: $_data['list'] = [ 'dingo' , 'engo' , 'fengo' , 'gingo' , 'autoFill'= ...

  9. 解决json结合struts2时,Class org.apache.struts2.json.JSONWriter can not access a member of * 的问题

    在使用json的时候,产生的一个错误,查了一下资料,原来是struts2和json一起使用的时候,才产生的问题,虽然不影响程序的运行,但是总是会有一些异常的日志产生,并且,这个也会增加程序的负担. 原 ...

  10. hbase zookeeper独立搭建

    一.zk单独搭建 1.修改配置文件:conf/zoo.cfg tickTime=2000 dataDir=/home/hadoop/data/zookeeper clientPort=2181 ini ...