>> 之前的Documenting不给力
在SolidMCP开篇中，我最自己如何写文档有了一个大概的设想：
至于Revisiting的方式，Blog、docbook、TiddyWiki、Comment in Doxygen Style甚至更多的Unit Test Cases的形式,皆可。
在过去一年的时间内，我尝试过docbook,TiddyWiki和Doxygen三种方式：
Doxygen Comment这种方式一直坚持了下来而且会继续坚持下去。只不过最开始使用Visual Studio中提倡的XML Style，最后则选择了更倾向于JavaDoc/QT的风格；
而对于docbook，也实践过，但是没有坚持下来，原来就在于比较docbook的Tag比较多，而且其本身为Xml，写起来比较复杂，而且可读性很差，每次要写点东西，感觉都必须大动干戈。
至于TiddyWiki这种东西，细想独特，可以用于建立小规模的知识库，但用起来还是觉得麻烦，结果也只能不了了之。
直接的结果就是，除了基于Doxygen的代码注释，其他方式的文档没有建立起来，最终还是MS Word或者直接在Blog内写几句了事。因此，Piaoger的Knowleadge Base在Document这块有些成果，总的来说做得比较失败。
>> 再思量
在重头考虑这个事情时，对于文档工具本身，我提出了下面这些要求：
Plain Text；
可读性比较强；
无需Editor也能很方便编写；
Tag比较少，多了记不住；
用户群较大；
便于输出为Html等其他格式；
在网上看了很久，最终能入围的其实也就是docbook、markdown和reStructuredText。
docbook可读性稍差，并且Tag较多，而且去年用起来并不是很得力，所以只能忍痛割爱；
Mmarkdown与reStructuredText二者旗鼓相当，reST甚至会成为Python Doc的标准，Github和Bitbucket也支持，
Markdown比reST则相对更简单些，似乎用的人也更多一些，甚至连Doxygen也支持Markdown。
基于上面的考虑，Piaoger最终考虑选择Markdown，但reStructuredText依旧会放在候选榜单内，做比较正式的东西它可能更适合一些。
>> Tools:
ReText
http://sourceforge.net/p/retext/home/ReText/
ReText 是一个使用 Markdown 语法和 reStructuredText (reST) 结构的文本编辑器，编辑的内容支持导出到 PDF、ODT 和 HTML 以及纯文本，支持即时预览、网页生成以及 HTML 语法高亮、全屏模式，可导出文件到 Google Docs 等。
而且ReText是基于Python/PyQt的开源软件，除了可以用来编写Markdown或者reST文档，也可日后参考参考。
Pandoc
Pandoc 一个用 Haskell 文档格式转换软件;
输入格式： markdown ,Textile, reStructuredText, HTML, LaTeX;
输出格式:markdown, reStructuredText, XHTML, HTML 5, LaTeX , ConTeXt,RTF, DocBook XML ...！
http://johnmacfarlane.net/pandoc/
>> 更多想法
在Github或者bitbucket上建立一个文档类的项目，直接存放*.md或者*.rst文件，但对于image之类的附件尚没有最终的想法。
>> References
Doxygen Markdown support
http://www.stack.nl/~dimitri/doxygen/markdown.html
Markdown 语法说明 (简体中文版)
https://github.com/riku/Markdown-Syntax-CN/blob/master/syntax.md
开源书和开源技术-Markdown篇
http://www.ituring.com.cn/article/828
Dillinger is a cloud-enabled HTML5 Markdown editor.
http://zh.wikipedia.org/wiki/Markdown
WMD：
Pagedown:
PageDown is the version of Attacklab's Showdown and WMD as used on Stack Overflow and the other Stack Exchange sites.
PageDown 一个用来解析和编辑 Markdown 内容的 JavaScript 库，可将 Markdown 转成 HTML 文本，并提供一个编辑器可实时预览生成的 HTML 效果。
PageDown 可在浏览器中使用，也可以在 Node.js 环境中使用。
https://github.com/OscarGodson/EpicEditor
http://joncom.be/experiments/markdown-editor/
http://daringfireball.net/projects/markdown/syntax
两个基于Markdown与Python的static blog generator：
https://github.com/lepture/liquidluck
http://schnouki.net/tag/golbarg/
About reST:
reStructuredText online renderer
http://www.tele3.cz/jbar/rest/rest.html
http://docutils.sourceforge.net/rst.html
http://docutils.sourceforge.net/docs/user/rst/quickref.html
蒋鑫的Got Github开源书
http://www.worldhello.net/gotgithub/
more:
An HTML5 slideshow generator based on Markdown or reStructuredText
https://github.com/n1k0/landslide
Static blog generator in python, using mardown/rest syntax
https://github.com/ametaireau/pelican
Slide Generator
http://bartaz.github.com/impress.js/#/bored
https://github.com/ksky521/webSlide/