如何写好一篇入门教程？

[HuYuee]

开篇我声明，是写入门教程的套路，并不是所有的教程都是如此。不喜勿喷..

我总结了下，入门教程要想写的好（被人点的赞多），首先我们得清楚看这个入门教程的人想知道什么。其实，无非就是三点：

1. 什么是xx？
2. xx主要包含什么内容？
3. 怎么使用？

什么是xx？

入门教程第一个标题一般就是，什么是xx？那么回答这个问题，核心描述一定得抓住。

核心要浅显易懂，要直入主题，一定不要搞一些复杂的专有名词（个人认为就是装X），不要说的花里胡哨。最好就是一句话。

这里我举了两个例子，比如：

MobX只做一件事，解决 state 到 view 的数据更新问题。

还有一个例子：

MobX 是一个简单、方便扩展、久经考验的状态管理解决方案。这个教程旨在十分钟内向你介绍 MobX 的一些重要概念。MobX 是一个独立的苦，不过大多数人都把它和 React 一起使用，所以本教程也就着眼于这个组合展开。

这里很清楚、很明显的能看到这两个回答的对比之处。

第二个例子太含糊其词了，状态管理，什么状态，如何管理的。到底是什么东西，这个到底有什么，用户还是不太明白你再说什么。所以入门教程最重要的就是尽量用不专业的名词，来解释专业名词。通俗的说就是入门教程的内容尽量要用小孩能听懂的词语来解释一个比较专业的东西，这是最重要的一点

xx主要包含什么内容？

这里我们需要交代这个框架或者这个技术他主要涉及到的技术点有什么内容，一定要配合图片

比如

核心理念

mobx 引入了几个概念，Observable state, Derivations 和 Reactions。

可以拿 Excel 表格做个比喻，Observable state 是单元格，Derivations 是计算公式，单元格的修改会触发公司的重新计算，并返回值，而最终公式的计算结果需要显示在屏幕上(比如通过图表的方式)，这是 Reactions。

作者通过一个图片来展示，主要涉及的就是三块，一个state，一个derivations，一个Reactions。并且通过Excel表格的比喻来解释这个核心理念，就更加通俗易懂了。

所以图片和通俗易懂的比喻更加能让读者明白

怎么使用？

怎么使用？当然就是一段能够快速上手的简单示例或者demo了。

没错，确实是这样。但是不仅仅是demo，而且一定要有可以在线调试的地址（方便读者可以快速练手或者快速改动代码看效果）。不明白？没关系，看看别的大神是怎么做的。如下图：

如上图所示，一个在线调试的地址和demo代码片段同样重要