技术文档写作

技术文档的特点

• 结构清晰
• 多人协作 （版本控制系统/WIKI）
• 利于回溯 （版本控制系统）
• 程序/脚本 语法加亮显示
• 程序/脚本 可直接 复制粘贴 用于生产环境
• 提供多种格式的文档 （.html, .pdf, .epub, .docx/.odt）

使用排版工具（如：M$ Word）的劣势

• 不利于回溯
• 不利于多文档搜索
• 不利于 程序/脚本 的语法加亮显示
• 不利于直接复制内容用于生产
  • Word 会自以为是的替换许多符号
  • Word 会包含许多不可见的控制字符

• LaTex -- 如何使用 LaTeX 排版论文

结构化文档的格式

• DocBook

• XHTML/HTML5（CSS）

• WIKI 标记语言

• 轻量级的文本标记语言

结构化数据格式

• XML
• JSON
• YAML

DocBook

• 使用语义化标签的 XML 文档

• 写作和发行过程

  • 使用 XML 书写图书源码
  • 使用 XSLT 读取 DocBook 的 XSL 文件将 XML 转换成 HTML
  • 生成 pdf 等格式

• 在 Linux 世界里广泛使用

  • The Linux Documentation Project

• DocBook 5: The Definitive Guide -- By Norman Walsh , O'Reilly Media

Wiki

• Wiki 系统
  • 将 Wiki 标记语言 转换成 HTML 页面
  • 利于多人协作，提供版本控制
  • 如： Dokuwiki, MoinMoin, Mediawiki
• Wiki 标记语言 （Creole）
• 各种 Wiki 系统（包括标记语言）的比较

轻量级的文本标记语言

• MarkDown -- 使用广泛
  • 方言：GFM
• reStructuredText -- Pythoner 的钟爱
• AsciiDoc -- 基于文本标记语言的 DocBook 实现，基本实现了 DocBook 的语义表达
  • AsciiDoc cheatsheet
  • 方言：asciidoctor
    • AsciiDoc Syntax Quick Reference
• 各种标记语言格式之间的转换工具
  • http://pandoc.org/
  • 在线转换：http://pandoc.org/try/

技术文档的写作方式

像写代码一样的方式写文档

• 使用文本标记语言书写文档内容
  • 使用纯文本编辑器 -- 如：Nodepad++， Editplus，Vim 等
  • 使用程序员偏爱的代码编辑器及其标记语言插件 -- 如：Atom，Sublime Text 等
  • MarkDown 专用编辑器 -- 如： MarkdownPad2、Typora
  • AsciiDoc 专用编辑器 -- 如： AsciiDocFX
• 使用文档格式转换工具（类此与对程序语言进行编译）
  • 生成 HTML、PDF 等格式的文件
• 将文档内容纳入版本控制系统
  • 记录修改历史并提供回溯
  • 多人协作

使用文档标记语言的 图书/文档 案例

• Front-End Developer Handbook 2017 -- MarkDown
• readthedocs.org docs -- reStructuredText
• ProGit 2nd ed -- Asciidoc

版本控制系统

• Git
• 代码托管服务（程序员的 SNS 社区）
  • github
  • bitbucket
  • 码云@oschina
  • https://code.csdn.net/
• 图书/文档 托管服务
  • gitbook -- https://help.gitbook.com/
  • readthedocs -- https://docs.readthedocs.io/
  • 看云 -- http://help.kancloud.cn/

SNS: Social Network Service

git 和 github

• 学习 git 参考
  • 为啥 Git 最棒
  • git 简易指南
  • git-recipes
  • git 教程
  • git 魔法 -- git
  • 10篇写给Git初学者的最佳教程 -- Top 10 Git Tutorials for Beginners
  • Git Book
• 学习 Github 参考
  • 《如何高效利用GitHub》
  • 《Got GitHub》(蒋鑫)
  • The GitHub Hep
  • 《GitHub入门与实践》([日]大塚弘记)
  • 《完全学会Git GitHub Git Server的24堂课》(孙宏明)

将一组文档构建成网站

• 选择你偏爱的静态网站生成工具
  • staticgen
  • staticsitegenerators
• BLOG
  • Pelican（Python）
  • Jekyll / Octopress （Ruby）
  • Hugo（Go）
  • Hexo（Javascript）
• BOOK
  • gitbook
    • 解析器 -- 基于 Node.js 语言的 gitbook
    • 支持的文档标记语言 -- Markdown（GFM）、AsciiDoc
    • 支持的版本控制系统 -- Git
  • Read The Docs
    • 解析器 -- 基于 Python 语言的 Sphinx
    • 支持的文档标记语言 -- Markdown （CommonMark）、reStructuredText
    • 支持的版本控制系统 -- Subversion, Bazaar, Git, and Mercurial

Markdown to Slide

Slide （HTML+CSS+JavaScript）

• md2googleslides
• slideshow