工具(5): 极简开发文档编写(How-to)

缘起

一个合格的可维护项目,必须要有足够的文档,因此一个项目开发到一定阶段后需要适当的编写文档。项目的类型多种多样,有许多项目属于内部项目,例如一个内部的开发引擎,或者一个本身就是面向开发者的项目。

本文考虑的是这种面向开发者的项目文档编写。通过本文,你将快速获得如下技能:

  • 理解开发项目文档的基本要素
  • 掌握编写有头有尾结构化文档的能力
  • 获得1个开发项目文档编写的模版项目和现成工具

感受

在开始之前,我们先通过几个现成的例子,直观的感受一个面向开发者的项目,其专业的文档应该是什么样的。我们通过直接截图的方式直接了当的表达这点。

Rust编程语言文档

文档地址:doc.rust-lang.org-2018
截图:

Julia编程语言文档

文档地址:docs.julialang.org-en-v1

截图:

BuckyCloud开发文档

文档地址:docs.buckycloud.com-zh-cn

截图:

小结一下,开发项目文档一般都具有如下章节:

  • 介绍(Introduction)
  • 快速开始(QuickStart, Helloworld, Getting Started...)
  • 整体介绍(Common/Core/Basic Concept, Architecture, Understanding...)
  • 开发手册(References)
  • 示例(Examples)
  • 知识库文章(Articles)

根据项目特点,不同类型的项目会做对应的取舍和顺序调整。

工具

工欲善其事,必先利其器。作为极简系列,我们直接了当的介绍我们的工具:

通过Gitbook可以在线编写文档,按照上一节的套路即可编写出相对专业的文档。但是Gitbook同时提供了一个命令行工具,使得我们可以直接在本地编写MarkDown文档,然后使用命令行工具把MarkDown转成文档网页。

Gitbook命令行工具如下,该工具基于nodejs编写,因此你需要安装nodejs:

因此你只需:

  • 创建一个git仓库
  • 创建完整的文档目录结构,并使用MarkDown编写章节内容
  • 编写脚本调用gitbook-cli转换文档目录为网页
  • 部署网页到线上即可,例如docs.example.com

快速体验

现在,我们可以通过几个命令来快速体验一下。

  • 首先,请安装nodejs:http://nodejs.org/
  • 其次,请克隆示例项目:git clone https://github.com/fanfeilong/doc.git
  • 接着,执行npm install来安装依赖的node modules。
  • 接着,在doc目录下执行命令生成文档:node doc.js docs.starlab docs.starlab.io
    • 注意docs.js的第一个参数是文档源目录,第二个参数是我们希望生成的网站目录
      • docs.js会自动安装依赖的gitbook-cli,首次安装会慢一些。
  • 可以看到浏览器已经打开了生成的文档:

文档目录设计

gitbook要求根目录下必须有如下三个MarkDown文档:

  • index.md
  • README.md
  • SUMMARY.md

示例中,我们虚拟了一个开发项目的文档目录docs.starlab,设计目录结构如下:

.
├── 1.QuickStart
│   ├── 1.1.InstallStarlabSDK.md
│   ├── 1.2.Hello,Starlab.md
│   ├── 1.3.UnderstandingStarlabApp.md
│   ├── 1.4.HowToDebugStarlab.md
│   └── 1.5.UnderstandingDebugger.md
├── 2.LearnStarlabSDK
│   ├── 2.1.IntrudoctionToStarlab.md
│   └── 2.2.CoreConcept.md
├── 3.Examples
│   ├── 3.1.CreateEarth.md
│   ├── 3.2.CreateMars.md
│   └── 3.3.CreateMoon.md
├── 4.References
│   ├── ref_fixedstar.md
│   ├── ref_meteor.md
│   ├── ref_planet.md
│   ├── tool_fixedstar.md
│   ├── tool_meteor.md
│   └── tool_planet.md
├── README.md
├── SUMMARY.md
└── index.md
  • 其中,index.md用来生成Introduction一节
  • 其中,README.md是gitbook需要的,一般我们让README.md和index.md的内容一样即可。
  • 其中,SUMMARY.md通过MarkDown来组织网页左侧的目录结构。

可以看一下SUMMARY.md的内容:

# Document

* [1. QuickStart](1.QuickStart/1.1.InstallStarlabSDK.md)
    * [1.1. Install StarlabSDK](1.QuickStart/1.1.InstallStarlabSDK.md)
    * [1.2. Hello, Starlab](1.QuickStart/1.2.Hello,Starlab.md)
    * [1.3. Understanding Starlab App](1.QuickStart/1.3.UnderstandingStarlabApp.md)
    * [1.4. How to Debug Starlab](1.QuickStart/1.4.HowToDebugStarlab.md)
    * [1.5. Understanding Debugger](1.QuickStart/1.5.UnderstandingDebugger.md)
* [2. Learn Starlab SDK](2.LearnStarlabSDK/2.1.IntrudoctionToStarlab.md)
    * [2.1. Introduction to Starlab](2.LearnStarlabSDK/2.1.IntrudoctionToStarlab.md)
    * [2.2. Core Concept](2.LearnStarlabSDK/2.2.CoreConcept.md)
* [3. Examples](3.Examples/3.1.CreateEarth.md)
    * [3.1. Create Earth](3.Examples/3.1.CreateEarth.md)
    * [3.2. Create Mars](3.Examples/3.2.CreateMars.md)
    * [3.3. Create Moon](3.Examples/3.3.CreateMoon.md)
* [4. References](4.References/ref_fixedstar.md)
    * [fixedstar](4.References/ref_fixedstar.md)
    * [meteor](4.References/ref_meteor.md)
    * [planet](4.References/ref_planet.md)
    * [fixedstar tool](4.References/tool_fixedstar.md)
    * [meteor tool](4.References/tool_meteor.md)
    * [planet tool](4.References/tool_planet.md)

注意:目录名和文档名不能含有空格,但是在SUMMARY.md里组织的时候,[text](relativepath)格式里的text可以起更友好的名字。

部署

如果需要部署,只需要把生成的网站部署到自己的网站服务器上即可。

你的尝试

相信,通过本文的方式,你可以为自己的项目快速构建内部或外部文档,如果你想了解doc.js做了什么,你可以直接阅读这个简短的工具脚本,按需定制。我用这个方式已经为好多个项目写了专业的文档,希望你也可以!GoodLuck!

--end--

posted @ 2018-12-05 03:33 ffl 阅读(...) 评论(...) 编辑 收藏