Markdown: 用写代码的思维写文档

时间:2022-09-18 07:57:58

作者:吴香伟 发表于 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]。

参考文献

  1. 如何在微信公众平台上优雅的写作

Markdown: 用写代码的思维写文档的更多相关文章

  1. 打开地图文件和shape文件代码加载Mxd文档

    代码加载Mxd文档 用代码添加Mxd文档,用到AxMapControl.LoadMxFile(sFilePath),我们只要将Mxd文档的路径传给这个方法即可 /// <summary>  ...

  2. 如何写出专业级OOP程序-----文档注释

    由于时间的限制就写一些通用的注释啦> @author 姓名 这个标记将产生一个作者条目,可以使用多个@author注释,每个对应一个作者. @version 文本 这个标记产生版本条目,对当前版 ...

  3. 看图写代码---看图写代码 阅读&lt&semi;&lt&semi;Audio&sol;Video Connectivity Solutions for Virtex-II Pro and Virtex-4 FPGAs &gt&semi;&gt&semi;

    看图写代码 阅读<<Audio/Video Connectivity Solutions for Virtex-II Pro and Virtex-4 FPGAs >> 1.S ...

  4. 使用Adminlite &plus; ASP&period;NET MVC5&lpar;C&num;&rpar; &plus; Entityframework &plus; AutoFac &plus; AutoMapper写了个api接口文档管理系统

    一.演示: 接口查看:http://apidoc.docode.top/ 接口后台:http://apiadmin.docode.top/ 登录:administrator,123456 二.使用到的 ...

  5. 使用Sandcastle 基于代码注释生成接口文档

    一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...

  6. ASP&period;NET Web API根据代码注释生成Help文档

    使用Visual Studio新建一个ASP.NET Web API项目,直接运行,查看Help文档可以看到如下的API帮助说明 如何在Description中显示描述. 1. 打开Controlle ...

  7. C&num; 代码注释生成代码提示和帮助文档

    C#文档注释格式: /// <summary> /// function description /// </summary> /// <param name=&quot ...

  8. C&num; 基于NPOI&plus;Office COM组件 实现20行代码在线预览文档(word,excel,pdf,txt,png)

    由于项目需要,需要一个在线预览office的功能,小编一开始使用的是微软提供的方法,简单快捷,但是不符合小编开发需求, 就另外用了:将文件转换成html文件然后预览html文件的方法.对微软提供的方法 ...

  9. MyEclipse保存文件时 自动格式化代码! 不包括文档注释

    设置不格式化 文档注释

随机推荐

  1. 浅谈requireJS

    项目中大都使用模块化开发,requireJS作为AMD模块开发的典范,所以有必要学习下.通过一步步利用requireJS编写demo,从而学习requireJS的一个整体开发流程以及自我使用requi ...

  2. python初识第二篇

    python 编码: 第一次编程有时候会遇到乱码的情况,就可以通过以下的情况来解决 在Windows中默认的就是gbk编码,如果在代码头两部定义utf-8,系统还会按照系统的方式来定义. python ...

  3. 使用XML定制Ribbon的一点小前奏(稍微再进一步的理解XML)

    定制文档级Ribbon界面的实现思路: 1.excel的文件使用rar+xml的形式保存在本地. 2.用压缩软件打开文件,以规范的格式直接编缉或添加xml文件 3.使用excel文件时,主程序会解析x ...

  4. &lbrack;转载&rsqb;iTOP-4412开发板搭建最小linux系统

    本文转迅为电子论坛:http://www.topeetboard.com 最小linux系统所需资料下载:http://pan.baidu.com/s/1kTNan0j 开发板不仅可以运行Androi ...

  5. layer 一款口碑极佳的web弹层组件&comma;弹框专用

    研究学习网址: http://layer.layui.com/

  6. 【转】Spark是基于内存的分布式计算引擎

    Spark是基于内存的分布式计算引擎,以处理的高效和稳定著称.然而在实际的应用开发过程中,开发者还是会遇到种种问题,其中一大类就是和性能相关.在本文中,笔者将结合自身实践,谈谈如何尽可能地提高应用程序 ...

  7. 【项目笔记】【bug】数组空指针异常

    package com.example.googleplay.ui.holder; import java.util.ArrayList; import android.view.View; impo ...

  8. Flask信号和wtforms

    一.信号 1.1.所有内置信号 request_started = _signals.signal('request-started') # 请求到来前执行 request_finished = _s ...

  9. js 表单序列化为json对象

    $.fn.serializeJson = function () { var o = {}; var a = this.serializeArray(); $.each(a, function () ...

  10. &lbrack;na&rsqb;TCP的三次握手四次挥手&sol;SYN泛洪

    1.TCP报文格式 上图中有几个字段需要重点介绍下: (1)序号:Seq序号,占32位,用来标识从TCP源端向目的端发送的字节流,发起方发送数据时对此进行标记. (2)确认序号:Ack序号,占32位, ...

相关文章