一个合格的可维护项目，必须要有足够的文档，因此一个项目开发到一定阶段后需要适当的编写文档。项目的类型多种多样，有许多项目属于内部项目，例如一个内部的开发引擎，或者一个本身就是面向开发者的项目。
本文考虑的是这种面向开发者的项目文档编写。通过本文，你将快速获得如下技能：
理解开发项目文档的基本要素掌握编写有头有尾结构化文档的能力获得1个开发项目文档编写的模版项目和现成工具在开始之前，我们先通过几个现成的例子，直观的感受一个面向开发者的项目，其专业的文档应该是什么样的。我们通过直接截图的方式直接了当的表达这点。
文档地址：doc.rust-lang.org-2018 截图：
文档地址：docs.julialang.org-en-v1
截图：
文档地址：docs.buckycloud.com-zh-cn
截图：
小结一下，开发项目文档一般都具有如下章节：
介绍(Introduction)快速开始(QuickStart, Helloworld, Getting Started...)整体介绍(Common/Core/Basic Concept, Architecture, Understanding...)开发手册(References)示例(Examples)知识库文章(Articles)根据项目特点，不同类型的项目会做对应的取舍和顺序调整。
工欲善其事，必先利其器。作为极简系列，我们直接了当的介绍我们的工具：
Gitbook通过Gitbook可以在线编写文档，按照上一节的套路即可编写出相对专业的文档。但是Gitbook同时提供了一个命令行工具，使得我们可以直接在本地编写MarkDown文档，然后使用命令行工具把MarkDown转成文档网页。
Gitbook命令行工具如下，该工具基于nodejs编写，因此你需要安装nodejs：
gitbook-cli因此你只需：
创建一个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.mdREADME.mdSUMMARY.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--
转载于:https://www.cnblogs.com/math/p/docs.html
相关资源：数据结构—成绩单生成器