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