就程序员如何写文档进行描述。
**1.叙述文 (禁止！) **
例子：使用纯CSS 实现Google Photos 照片列表布局· Issue #4 · xieranmaya .
样式如下：
一开始，我想要这样做。
….
发现了这样做有这样的结果，那么该如何修改呢？
…..
这样做的话,
…..
这种文章以叙述文的形式出现，语言冗余，重点不清晰，阅读量大。有时候，我们需要的是两点之间该如何走，而不是走路的时候的记忆。
2.详解类文章
范例1：代码内容短小
分析——适合内容：
- 代码内容少
- 依赖性低
范例2：解决复杂以及强依赖的内容
依赖性强或者复杂的代码产生的问题：
- 这些代码往往有版本和依赖，因此在代码不完整时候容易出错。 (若是第一步就出错，就无法证明代码的正确性，读者便会离开。)
为了解决复杂代码难以测试，常用的方法有：
- **压缩包 (提供下载地址，如图上download位置) **。将大部分环境打包进压缩包，再通过大家共识地方式进行打开运行 (或：简单的文字进行叙述) 。
- 在线运行。
- 文章中贴完整且简单的代码贴，相关依赖挂载在网上。** (不需下载，相当于使用服务) **
提供完整代码的环境，亦是文档的正确性的验证。
扩展：文章分层
文档分层，亦是非常重要的，就如同为了让代码更有可读性，我们常常使用模块进行分装并引用。
常用的解决方案：
1) 外部链接
多用于：带层次的内容。
收缩方式
和外部链接类似，用于层次感的内容。如：一篇文档面对的读者究竟是什么层次的读者，初级的和中级的，需要呈现的内容是不一样。
外部链接的方式更为互联网，将内容集中于一个文档进行处理，减少重复操作。
**收缩方式 (基于iframe) **
收缩方式+外部链接的方式实现的。拥有外部链接的优点 (减少重复文字) ，又有收缩方式的表现方式。
tag方式
不少文档，支持使用tag (#号标识) 功能。通过输入tag，就能跳转到文档的指定位置，从而实现文档内的跳转。
这种方式更加精确化了内容的定位，适合同一层次内容的文档。 (如：API文档)