如何编写文档

目的

明确编写文档的目的，是为了给谁看？要达到什么样的效果？

比如文档的几种类型：

  1. Tutorials 教程 - 简要的介绍
  2. How-tos 新手教程 - 一步一步的操作步骤
  3. Guides 指引 - 详细全面的说明

受众

了解受众是谁，可以明确内容的详细程度。例如给程序的可以简化内容，给美术的需要一步一步教等等。

边做边写

在做东西的同时，收集记录整理文档，要把这一过程作为工作的一部分。如果都放在最后统一整理，会导致文档不全面。

  • 收集
  • 梳理
  • 实践
  • 编写

验收

文档拟制合格的标准是什么？技术文档写到什么程度就算是写好了？八个字：逻辑清晰、条理分明。

写完后阅读一遍，在阅读的过程中找问题，看看哪里表述不清，看看整体的结构是否清晰。

使用 Markdown

Markdown 是什么？

Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯。它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。

为什么使用 Markdown？

因为语义，简单说就是需要使用一些符号来表示不同文字实际的语义，例如这是标题、引用、还是列表等等。

这些语义信息必须使用额外的符号来表达，当然有很多种标记语言，其中 Markdown 是最简单易学的，也是使用范围最广的，很多网站都内置对 Markdown 的支持，如 GitHub。

类似的标记语言有：Markdown, reStructuredText, MediaWiki, AsciiDoc, Org-mode

Markdown 优点

  1. 简单，要掌握的概念很少
  2. 都是文本，易于进行版本控制

Markdown 语法

需要了解 Markdown 基本语法，例如：标题、列表、代码、引用、图片、链接等等。具体可以参考网上的文章。

Markdown 编辑器

使用高效的 Markdown 编辑器可以大幅提升效率

优质的介绍文章：

风格要求

合理使用标题

标题原则上存在六级，即一级、二级、三级、四级、五级和六级标题。

但实际上一般一级标题留作文章标题使用，实际可使用的推荐只使用二级、三级、四级这三个层级，再多层级只会觉得结构不清晰。

合理使用图片

合理使用图片，有些时候一图胜千言。

合理使用表格

使用表格可以方便地对比数据，要比解释性的段落文字更易突出区别。

排版规范

参考资料