程序员如何写文档

  • date_range 2018-11-20 info
    sort
    private
    label
  1. **1.叙述文 (禁止!) **
  2. 2.详解类文章
  3. 扩展:文章分层

就程序员如何写文档进行描述。


**1.叙述文 (禁止!) **

例子:使用纯CSS 实现Google Photos 照片列表布局· Issue #4 · xieranmaya .

样式如下:

一开始,我想要这样做。

….

发现了这样做有这样的结果,那么该如何修改呢?

…..

这样做的话,

…..

这种文章以叙述文的形式出现,语言冗余,重点不清晰,阅读量大。有时候,我们需要的是两点之间该如何走,而不是走路的时候的记忆。


2.详解类文章

范例1:代码内容短小

1542856798226

分析——适合内容:

  • 代码内容少
  • 依赖性低

范例2:解决复杂以及强依赖的内容

例子中,提供下载链接

依赖性强或者复杂的代码产生的问题:

  • 这些代码往往有版本和依赖,因此在代码不完整时候容易出错。 (若是第一步就出错,就无法证明代码的正确性,读者便会离开。)

为了解决复杂代码难以测试,常用的方法有:

  • **压缩包 (提供下载地址,如图上download位置) **。将大部分环境打包进压缩包,再通过大家共识地方式进行打开运行 (或:简单的文字进行叙述) 。
  • 在线运行
  • 文章中贴完整且简单的代码贴,相关依赖挂载在网上。** (不需下载,相当于使用服务) **

提供完整代码的环境,亦是文档的正确性的验证。


扩展:文章分层

文档分层,亦是非常重要的,就如同为了让代码更有可读性,我们常常使用模块进行分装并引用。

常用的解决方案:

1) 外部链接

1542858726120

多用于:带层次的内容。


收缩方式

1542869275174

和外部链接类似,用于层次感的内容。如:一篇文档面对的读者究竟是什么层次的读者,初级的和中级的,需要呈现的内容是不一样。

外部链接的方式更为互联网,将内容集中于一个文档进行处理,减少重复操作。


**收缩方式 (基于iframe) **

收缩方式+外部链接的方式实现的。拥有外部链接的优点 (减少重复文字) ,又有收缩方式的表现方式。


tag方式

1542869825713

不少文档,支持使用tag (#号标识) 功能。通过输入tag,就能跳转到文档的指定位置,从而实现文档内的跳转。

这种方式更加精确化了内容的定位,适合同一层次内容的文档。 (如:API文档)