【从 0 开始学习技术写作 #1】给初学者的技术写作

近期从产品经理转职为 Technical Writer，为了加强自己的技术写作能力，我决定将自己学习技术写作的过程记录下来。

关于 Technical Writing 的学习资源非常多，我研究了 Google Technical Writing, Gitlab Technical Writing 以及 Amazon 上的书籍。最终决定先从 WRITE THE DOCS 这个学习资源起手，它是目前我看到学习资源最丰富的网站。

这篇先从 《A beginner’s guide to writing documentation》开始。

---

为什么要写技术文件 ?

主要有 5 个原因

1. 6 个月后你还会使用到自己写的程式码

6 个月后我们会忘记当初为什么写下这段程式码，写文件是帮助未来的自己恢复记忆。

在纪录文件的过程中，我们写下了 why (为什么) 这段程式码要这样作，帮助我们理清思绪。

为了让自己在未来看得懂，我们间接的培养照顾读者 (care your readers) 的心态。

2. 你想要别人使用你的程式码

身为开发者，我们想要其他人使用我们的程式码，但前提是必须让人理解「用你的程式码有什么好处」。
别人要如何使用你的程式码呢？他们必须看得懂

这段程式码可以达成什么目的如何安装你的程式码了解与会使用你的程式码

如果你爱护自己的专案，就需要写清楚文件。

3. 你想要别人帮助你

当我们成为 Open Source 软体开发者时，总会希望有 contributor。

Contribute 只发生在 Open Source 有使用者、有文件、放了很多心力的情况下。

4. 你想要让程式码写的更好

写文件能帮助自己设计程式。

例如在替 API 写说明文件时，写下自己为什么要这样设计，能帮助自己思考。

5. 你想要成为一个更好的 writer

写文件就是在做长期的写作肌肉训练，愈写愈好、愈不写愈难重新启动。

---

如何开始写技术文件 ?

从简单的步骤开始:

用列点写大纲从 README 开始从使用 markup language (标记语言) 开始

慢慢培养写作肌肉，养成写文件的习惯。

---

技术文件要写给谁看?

从简单开始，只需要先瞄準 2 种人:

UserDeveloper

前者只管如何使用 (how) 但不管程式码如何运作;后者想要 contribute 因此需要了解 Code 的运作方式。

---

文件要写什么 ?

写以下内容:

这个专案要解决什么问题: 参考例子 Python Library designed to execute shell commands remotely over SSH- Fabric

一小段程式码展示这个专案的功能: 参考例子 HTTP library for Python

程式码和 issue tracker 的连结: 参考例子 The Hitchhiker’s Guide to Python

常见问题 (FAQ): 参考例子 Tastypie Cookbook

使用中碰到困难时如何取得协助: 常见方式有 Mail, Community, IRC Channel, 通讯软体 (Discord/ Slack...)。参考例子 FAQ: Getting Help | Django documentation

其他人如何 contribute: 参考例子 Contributing — OpenComparison documentation

安装指南: 参考例子 Installation — Read the Docs 2.7 documentation

专案授权形式 (Project license): 可使用 Open Source Project license 快速查询网站: Chooselicense

---

参考资源

A beginner’s guide to writing documentation