Markdown: 用写代码的思维写文档
作者:吴香伟 发表于 2014/08/07
版权声明:可以任意转载,转载时务必以超链接形式标明文章原始出处和作者信息以及版权声明
本文不讲解Markdown的语法规则,只关注它带来的好处以及我使用的方法。语法规则可以参考Markdown: Syntax。
文档内容和格式分离
使用Word写文档总花费很多时间在调整格式,并且往往最终也没让自已满意。这对有洁癖的人来说痛苦非常。Markdown只通过几个简单的符号表示文档的格式,比如##代表二级标题,**X**代表强调内容X,*X*代表X的字体为斜体等。这种方式同HTML非常相似,但Markdown的符号更加简洁。这就是它的设计哲学“易读易写”,我们直接阅读Markdown的源代码(注意,这里指带有Markdown标记的文档)不会因为有太多的标记符号而感觉到吃力。也正因为Markdown这套标记符号的简单和抽象的特点,从而能够让写作的人专注于内容。为什么说这套标记符号是抽象的?举个例子,符号“##”只标明它后面的内容是二级标题,但没有定义二级标题的具体格式。具体格式和标记符号之间的关系就是面向对象中具体实现类和接口的关系。将书写好的Markdown源代码转换成常用的文件格式(如HTML、DOCX和PDF等)要借助一款转换工具,转换工具会实现标记符号对应的具体格式。在众多转换工具中,我觉得Pandoc是不二选择。
BTW,如同写代码一样,去耦合两样东西的惯用手法就是在这两者之间引入抽象层。标记符号就是Markdown中的一个抽象层,解耦了文档内容和文档格式,从而让两者可以独立开发而不用关心彼此。
文档整体和部分松耦合
目录结构、命名规则、转换命令
我用下面的目录结构来写文档,在顶级目录sds-doc下主要包含四部分内容:chapters、images、reference和一个README.txt文件。Chapter目录下保存文档的各个章节,比如我这份文档中就包含balance、common等章节;Image目录用于存放每个章节用到的图片,它的子目录结构和chapter子目录的结构保持一致;Reference目录用于保存文档中引用到的第三方文档。README.TXT文件记录使用pandoc转换markdown文件的命令。
sds-doc
|-- chapters
| |-- balance
| |-- common
| |-- consistency
| |-- integrate
| `-- storage
|-- images
| |-- balance
| |-- common
| | | |-- 1.jpg
| | | |-- 2.jpg
| |-- consistency
| |-- failure
| `-- integrate
|-- README.txt
|-- reference
| |-- Amazon_Dynamo论文中文版.pdf
| |-- Erasure-Codes-For-Storage-Applications.pdf
| `-- Google-File-System中文版_1.0.pdf
`-- sds.md
这看起来非常像Project的目录结构,README文件就是编译脚本。我们可以在该文件中指定转换哪些内容,不转换哪些内容,因此可以很灵活地控制最终文档包含的内容。
另外,文档中经常引用文档内的其它章节,我们可以对被引用的章节设置个ID,那么引用的地方就可以根据ID号来引用了。为避免ID名字命名出现混乱,我们根据文档的目录结构来命名章节的ID编号。例如,对sds/chapters/storage/raid小节的ID号,命名为sds_storage_raid。
文档持续集成和虚拟化写
“冰冻三尺非一日之寒”,写技术类的文档不像写小说想到哪里就写到哪里,并且还越写越来劲。我对写文档的态度是,先把技术理解透彻再开始写文档,这样就能够做到一气呵成。但是,理解是个循序渐进的过程,所以文档的准备工作也是个与日俱增的过程。因此,我使用Git来管理平日的小理解,随着理解的深入持续地进行加工修改。
使用Markdown+Git写文档的另一个好处是,当有多个人共同写同份文档的不同章节的时候,如果采用Word必定每个人的文档格式都有自己的风格。但是,如果大家都使用Markdown写文档,最后使用相同的转换脚本,那么格式就会无比地一致。使用Git也可以很好地合并控制每个人的输出。
Markdown在微信公众账号中的使用
最近开始玩微信公众账号,但它的编辑器太简陋了,连最基本的一级标题、二级标题都没有,更别提代码语法高亮功能了。虽然它暂时不支持markdown格式,但我们仍然可以在它的编译器中使用markdown语法,然后使用一款名叫markdown here的浏览器插件就能够轻松搞定了。具体过程参考文献[1]。
参考文献
Markdown: 用写代码的思维写文档的更多相关文章
- 打开地图文件和shape文件代码加载Mxd文档
代码加载Mxd文档 用代码添加Mxd文档,用到AxMapControl.LoadMxFile(sFilePath),我们只要将Mxd文档的路径传给这个方法即可 /// <summary> ...
- 如何写出专业级OOP程序-----文档注释
由于时间的限制就写一些通用的注释啦> @author 姓名 这个标记将产生一个作者条目,可以使用多个@author注释,每个对应一个作者. @version 文本 这个标记产生版本条目,对当前版 ...
- 看图写代码---看图写代码 阅读<<Audio/Video Connectivity Solutions for Virtex-II Pro and Virtex-4 FPGAs >>
看图写代码 阅读<<Audio/Video Connectivity Solutions for Virtex-II Pro and Virtex-4 FPGAs >> 1.S ...
- 使用Adminlite + ASP.NET MVC5(C#) + Entityframework + AutoFac + AutoMapper写了个api接口文档管理系统
一.演示: 接口查看:http://apidoc.docode.top/ 接口后台:http://apiadmin.docode.top/ 登录:administrator,123456 二.使用到的 ...
- 使用Sandcastle 基于代码注释生成接口文档
一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...
- ASP.NET Web API根据代码注释生成Help文档
使用Visual Studio新建一个ASP.NET Web API项目,直接运行,查看Help文档可以看到如下的API帮助说明 如何在Description中显示描述. 1. 打开Controlle ...
- C# 代码注释生成代码提示和帮助文档
C#文档注释格式: /// <summary> /// function description /// </summary> /// <param name=" ...
- C# 基于NPOI+Office COM组件 实现20行代码在线预览文档(word,excel,pdf,txt,png)
由于项目需要,需要一个在线预览office的功能,小编一开始使用的是微软提供的方法,简单快捷,但是不符合小编开发需求, 就另外用了:将文件转换成html文件然后预览html文件的方法.对微软提供的方法 ...
- MyEclipse保存文件时 自动格式化代码! 不包括文档注释
设置不格式化 文档注释
随机推荐
- Processing简明教程与Java平台移植方法
1 Processing 1.1 Processing简介 Processing是一种具有革命前瞻性的新兴计算机语言,它的概念是在电子艺术的环境下介绍程序语言,并将电子艺术的概 ...
- JS定时程序,设定一个一直刷新,又时间间隔的js,读取当前的时间并显示
<!doctype html><html><head><meta charset="utf-8"><title>无标题文 ...
- .NET ORM工具Pax实战
Pax是微软的一个ORM读写工具,比NHibernate更好用.可以在项目中用Nuget下载并安装. 可以看到引用中多了 在App.config里设置配置文件如下 <?xml version=& ...
- 利用nginx来屏蔽指定的user_agent的访问以及根据user_agent做跳转
对于做国内站的我来说,我不希望国外蜘蛛来访问我的网站,特别是个别垃圾蜘蛛,它们访问特别频繁.这些垃圾流量多了之后,严重浪费服务器的带宽和资源.通过判断user agent,在nginx中禁用这些蜘蛛可 ...
- gfw列表
https://raw.githubusercontent.com/gfwlist/gfwlist/master/gfwlist.txt
- MongoDB-JAVA-Driver 3.2版本常用代码全整理(4) - 地理空间索引
MongoDB的3.x版本Java驱动相对2.x做了全新的设计,类库和使用方法上有很大区别.例如用Document替换BasicDBObject.通过Builders类构建Bson替代直接输入$命令等 ...
- c++多态
#include <cstdio> using namespace std; class Base { public: virtual void A() { puts("Base ...
- Java类额应用
基本数据类型包装类 Integer Character 其他的都是将首字母大写; 包装类和基本类型之间的转换: Integer int Integer i = new Integ ...
- Unity3D 物体移动方式
1. 简介 在Unity3D中,有多种方式可以改变物体的坐标,实现移动的目的,其本质是每帧修改物体的position. 2. 通过Transform组件移动物体 Transform 组件用于描述物体在 ...
- windows下用navicat远程链接虚拟机Linux下MySQL数据库
今天想用navicat远程连接虚拟机中的MySQL数据库,一直连不上,在网上搜索了一下,发现原因是MySQL对远程用户登陆的授权问题.这里说一下我的解决方法.(本人小白) 首先,我用navicat去远 ...