5. 项目说明文档

很多人忽视这个说明文档,往往给自己的项目工程建立一个空readme文件或者在里面随便写几行不清不楚的文字,这样非常不利于代码工程的后期管理,尤其是对于有团队协作的项目,即使是个人项目,考虑到后期可能要给别人用,写一份合适的说明也十分必要。

项目说明文档业界称为readme文档。

  1. 自己的项目代码的根目录中建立一个readme.md文件,注意扩展名为md,这样gitlab就可以自动识别并在这个项目主页上自动渲染(将源码翻译成html)这个文件了。

  2. 学会使用Markdown语法,充分利用文档的“插入图片”、“嵌入代码”、“标题分级”、“超链接”等功能,将内容“富”起来,尤其是图片和超链接,可以弥补文本文件表达的不足。

  3. 开头的简介很关键,readme文档的主要意义在于向读者描述你这个项目做了什么,运行在什么环境,如何使用,所以在文档的开头首先要简要介绍这个项目的存在意义,为什么要做这个,主要解决什么问题,运行在什么环境,如果需要与别的项目配合,那么你的项目处于什么样的位置。

  4. 必备信息,由于是开发工程,所以很多信息是必须要在文档中说明的

     - 开发环境的搭建
     - 开发中使用到的工具
     - 开发编译和系统运行的必要参数
     - 项目中的文件和目录结构信息
     - 编译或安装步骤说明
     - 使用示例
    
  5. FAQ

     - 记录项目中经常会被问到的问题
     - 记录项目的上的一些异常
    

results matching ""

    No results matching ""