原文： How to write a Good Technical Tutorial
如果你是一名软件开发人员，你便能理解在编码时为了解决特定问题，开发人员会有多频繁地进行谷歌搜索。
每个开发人员都会查看在线教程来解决他们遇到的问题。为了帮助解决你的问题，这些教程应该带有一些对于你和其他读者来说更有价值的东西。
写好一份技术教程，你需要牢记几点。
了解你的读者
清楚为谁而写很重要。你需要决定文章包含哪些内容，省略哪些内容。
你也不希望读者在阅读中途就放弃了。有时，你只需要写必要信息，不用什么都写。
参考这篇文章《如何更改HTML中的背景色》，读者想要知道更改HTML中背景色的方法。
作者直接列出了不同的设置方法，而并没有从“什么是HTML和CSS”写起。
还要记住，教程是写给入门人员看的还是资深人员看的——要尽量写明（可以在必要条件部分写明，或者只提一句教程是写给谁看的）。这将有助于确定你如何阐述内容以及预设读者的背景知识等。
写一个大纲
在开始写教程之前，先列出内容大纲。
以我正在写的这篇文章为例，为了说明如何写好一份技术教程，一开始，我把我会采用的不同步骤都写下来。
这个过程可以帮助你搭建一个合理的文章结构。你就能够解释具体的步骤，而不是想到什么写什么。
看看我写这篇文章时列的大纲：
一旦知道自己将要写什么，你就更容易专注于写作，并且不遗漏任何要点。
指出你要解决的问题
在一篇教程中，读者会首先查看该教程将解决或回答的问题是什么。这有助于读者判断所看文章是否就是自己需要的。
为了确保你的读者会进一步阅读，告诉他们你在解决什么问题，描述教程的目的，教程提供的价值，以及读者能收获什么。
你可以直接在介绍部分告诉读者该教程在做什么或者讨论什么。
回顾本文的介绍部分：当我说“写好一份技术教程，你需要牢记几点”时，我就是在告诉你，我们将讨论什么以及你将学到什么。
列出读者完成教程所需的前提条件
你应该告诉读者你将在教程中使用哪些工具、服务和资源。
你不会希望你的读者半途而废。如果他们在教程中途才得知你会用到其它工具或者他们不熟悉的东西，他们会泄气的。
只需要列一个清单，里面描述你要使用到的东西，以及这些东西是免费还是付费的。这有助于读者在实践教程之前就做好准备。
使用标题和短段
使用标题将文章的不同部分按主题分开。这样，读者每次看到一个新的标题，他们就会更清楚文章接下来是讲的什么内容。
如果你要描述一系列事情，可以试着使用标题或副标题来展示该系列中的每个元素，然后使用短段来做简要说明。
使用标题也会有助于SEO（搜索引擎优化），而且教程会看起来更有说服力，更容易实践。
提供代码片段
在技术教程中提供代码片段通常很有用。
这样，你的读者就会知道你在做什么，以及你想通过那段代码实现什么。
此外，将代码分解成小块，这也会便于你对代码进行解释（不必一次性解释所有代码）。
使用注释，描述你在某处使用特定代码的原因。另外，恰当地格式化代码也可以增强代码可读性。
举个例子：
# 以下注释描述了该程序的功能。
# 该程序输出Hello, world!
print('Hello, world!')
像这样使用代码片段。
结尾
我希望本文内容能帮助你写出清晰实用的技术教程。按照这些步骤写作，你将能够为读者提供更多的价值。
谢谢你阅读本文！