Skip to main content

如何写技术文章 - Part 1

如何给写一篇技术文档？Google 给出了一个 教程。本文是一篇笔记。

本文的目标​

  1. 快速预览这个教程的重要观点
  2. 在总结中学习

非本文的目标​

  1. 提供更多例子和练习
  2. 针对某个项目的技术文档做解读

遣词​

  1. 定义术语要注意

  • 不要重复定义，可以link到前面到定义

  • 如果定义很多，把他们收集到一个目录里

  • 不要中间变换写法

  • 使用缩写要先解释，不要在全拼和缩写里面来回横跳，不要给缩写使用几次的术语，定义术语要满足

    • 缩写明显更短
    • 文章中出现很多次
  1. 使用代词
  • 永远在名词后使用指代他的代词
  • 名词和他的代指之间超过五个词，还是再用一次名词吧
  • 如果名词和代指之间还有其他名词，还是再用一次名词吧

造句​

  1. 尽量使用主动语态

    被动语态既没有让事情更客观，有时候也完全省略了动作的发出者，让人产生更多疑惑。

  2. 造句要注意

  • 让句子清楚

    • 使用确定的动词，避免happen，occur，be动词（is are等）。
    • 去掉 There is/are。
    • 最小化使用形容词和副词，不要搞的和销售材料一样。

  • 让句子更短

    • 短句更有易读，好维护。这对文章来说也是一样的。
    • 一个句子只表达一个意思。
    • 把长句变成列表。留意句子里的分号和or。
    • 去掉无用的词。

      is able to 直接替换成 can 就得了

    • 如果从句偏离了主句的主题，就拆成两个句子。

成文​

  1. 织句成段
  • 要有一个好的开篇，着重于主题
  • 一段只有一个主题
  • 一段不要太长和太短
  • 回答What，Why，How
  1. 读者
  • 文档 = 读者要需要做一件事的知识 - 他们已有的知识
  • 不要用习语，
  1. 文档
  • 开宗明义，解释文章的目标和非目标
  • 清楚的指出文章的读者，以及他们需要已经掌握的知识（和前面第六条的公示结合，只有明确读者已有的知识，才能准确的找出和需要达成目标的差。
  • 在开头总结观点
  • 在需要的时候比较你和其他概念，这些概念也许读者已经熟知。