云顶国际

　　当然这个说法很笼统，我其实真正想说的是，一篇好的教程在我心目中应该拥有哪些特征，并不是说我的每篇教程都能够达到所有这些标准，也不是其他人对教程的评判不能有其他的标准。

　　为了严谨性，请允许我再加几个定语，LOL赛事押注一个是“以理科为内容”，也就是“以逻辑和理论为指导的学科”，这其中显然不包括绘画和搬砖；另一个是“以文字为主”，也就是说不考虑视频、MOOC之类的形式，教程主体应当是一篇文章，文章中可以夹杂其他媒体形式；最后一个是“以传授知识为目的”，也就是说主要是为了将笔者所想教授的知识传输到读者的头脑中、尽可能地保证不出现差错LOL赛事押注，而非为了激起读者的某种创造性思考——倒不是说这不好，而是这超出了我这里所说的“教程”的功能。

　　如果要综合这三条定语，找到一种最符合描述的文档的话，那可能是——高数课本。

　　不过，现有的绝大多数高数课本恐怕在我心中都称不上“好”，也许这就是我高数学得不好的原因吧。（不要推锅啊喂）

　　这两点看似是显而易见的，然而实际上许多教程在写作时并没有明确的范围和对象——比如我翻了翻手边的高数课本，基本上只是草草地写上一句“面向本科生”，顶多是“非数学专业地本科生”罢了。

　　当然，我不是说要像数学定义那样精确地对它们进行描述，这往往也是做不到的，而是说一篇教程的作者必须在开始写作之前就有一个大致的印象。其中，内容的范围通常而言比较容易确定，你可以试着养成列内容大纲的习惯，并借助于思维导图、将知识点绘制成树的方式——另一方面，在写作过程中对内容进行增删是相对容易的，我个人经常采用这样的方式：除了一条主线以外，其他内容想到哪里写到哪里，写完之后再根据难度曲线、相关性等情况更改。

　　确定教程所面向的对象往往更加困难，因为作者本人作为领域内的经验者通常难以判断读者到底会想什么，一个有效的方法是建立读者的侧写，也就是在头脑里假想处一个读者，并从其视角出发审视你的文字。侧写中的重点包括，读者的数理知识水平、对所讲授领域的认识、阅读文章的目的和心态、年龄和性格，实际操作中，你可以选取一个合适的熟人，想象他/她会怎样看待你的文章。

　　就我个人而言，我往往所想象的读者形象是一个高中数学还不错的本科大学生，具有基本的逻辑思维能力和旺盛的好奇心，并且愿意静下心来、花上半个小时左右认真阅读我的文章，我通常也会将文章篇幅控制在这个范围内。

　　需要意识到的是，你的读者不可能都符合你的这种想象，而总会有一些出入，同时你也不能假定你“从读者视角出发”得到的看法都是符合实际情况的，总会有你觉得读者能理解、但实际上没能理解的部分，反之亦然。

　　处理这一问题的方法主要在于在文章中留下余地，也就是保持解释和类比比必要的多出一些、思维的速度比必要的慢上一些。这一余地的大小是很难进行精确描述的，我只能说这需要靠你在写作中积累经验，同时也找到自己真正所想面向的读者。请记住，你所覆盖的人群越广，内容的深度就越浅、写作难度越高，这些方面总是矛盾的。当然，掌握更多的写作技巧可以帮助你降低它们的乘积，我们会在本文的剩余部分介绍它们。

　　从结构上来说，一篇文章最重要的部分是思路，不过这不是在说总体的内容，因为我假定你在写文章之前就基本确定了“立意”或“主旨”——对于“理科”来说，如果你真的不知道该说什么，那建议你还是赶紧去学点什么为好，而不是出来误人子弟。你要做的是像一个编剧，为了表达出你的“主旨”构建一条合适的剧情线，并且填入人物、事件和台词。

　　当然，这并不要求你真的去学习编剧，因为思路也是有规律可循的。常见的结构是3层，第一层是章，每章介绍一个主题，主题之间往往没什么直接的逻辑关系；主题中往往有几个终极结论，而为了得到终极结论需要一些阶段性结论，结论之间存在明显的依赖关系，不过不一定成线性；而从结论到结论又需要一些推理步骤，以及一些解释性的部分，这些步骤基本上是线性的，一串三段论直接到底的那种。简而言之，还是高数课本那样。

　　实践中的结构自然并非如此死板，一般一篇博客的内容也就一章，第一层结构基本可以直接省略，而考虑到知乎这种文字平台的使用模式，结论之间往往也并不真正形成网状关系LOL赛事押注，通常也就是线性结构，只在途中留下一些外部链接或者参考之类的，允许感兴趣的读者深入了解。

　　另一方面，与“结论”这个听起来就很数学的词比起来，可能“节”这个词对大部分人更友好，不过我想要强调的是，一个“结论”往往是可以浓缩成一句话甚至一个词的东西。一个有效的方法是，你可以试着在一章的主题下列出几个关键词LOL赛事押注，然后为它们排序，接着在关键词之间构建逻辑关系，从而得到这章的结构和大纲。

　　“结论”这一层次存在的重要意义在于，你可以在一些关键的地方地方留下“屏障”（barrier，与内存屏障双关，不过我不觉得有多少人能看出来），也就是保证到文章进行到某个地方时，大部分目标读者都能够理解你所希望他们理解的东西。

　　另一方面，存在“屏障”意味着你可以将文章切成好几个部分，为每个部分指定一个具体的目标——如果读者在到达屏障时完成了这一部分的学习目标，那么他/她可以休息一下、喝口水，如果没有的话，你则可以加入更多的解释来保证读者能够顺利理解。屏障保证了大部分读者的（学习）进度保持一致，也与你的想象保持一致，这能让你更容易地让自己的文字被不同水平的人所理解。

　　实际上，高数课本中也有许多值得学习的地方，比如你可以在“屏障”附近留下一些问题，因为读者往往很难发现自己并没有真正看懂之前的内容，一个简单、客观的问题可以帮助他们意识到这件事，并且主动往前翻找答案，从而加深自己的理解。当然，别忘了留下答案，让读者验证自己的想法是否正确。

　　在确定下来之后，结论往往相对是难以增删的，除非你愿意大段大段地删掉自己写好的东西，不说别人，我自己这么做都心痛。

　　相对地，结论之间的步骤是比较灵活的部分，你可以根据读者的水平、文章的节奏和篇幅情况等进行调整；同时，步骤也是最具变化性的部分，一千个人可能写出一千份相同的大纲，但是每个人的遣词造句肯定千差万别。

　　节奏的核心是速度，速度的快慢决定了读者怎样对待你的每一个章节。这一点上来说，教程的写作，注重的是一个起承转合——起，即起因，复习之前的内容，开启整节内容；承，即承接，从前提出发进行一些基本的演绎，节奏逐渐加快；转，即转折，也是整节的高潮部分，是最重要、最核心的部分，节奏也最快；合，即总结，高潮渐隐，结论浮现，让读者得以回顾一下前面的叙述，思考一下过程中到底发生了什么。

　　具体来说，节奏慢意味着较短的段落和句子、较稀疏的重点、较显然的过程，节奏快则反之。——当然我这里的“长”也不是叫你几行字不加标点，或者一段四五百字什么的。实践中，长的句子（指的是两个语气上的停顿之间的距离，这个停顿可以是句号，也可以是分号或者别的什么）大概在60个字左右，最多不要超过100个字，而长的段落一般也就300个字不到教程知识，再长的话阅读起来就比较困难了。短的话则没有最短只有更短，停顿之间可以只有一两个字，一段也可以只有一两行，我一般习惯长短之间的比例比较悬殊，这样会更有韵律感。

　　如果你的写作水平无法让你在写的时候就很好地把握住文字的结构的话，你也可以试着在写完之后通读一遍再进行更改，我的经验是睡一觉起来再看之前写的东西，会能够发现很多之前没有注意到的问题。尤其是文字的起伏顿挫这种，由于写的速度比读要慢得多，往往在一开始写的时候很难发现这方面的问题，通读一遍能够让你体会作为一个读者的真实感受——当然条件允许的话找一个朋友做这件事则更好。（不就是找个编辑么）

　　请记住，不要死板。步骤的安排是可以非常灵活的，不一定得是一串递进式的推导，你可以试着从下一个结论反推到上一个结论、或者是倒叙（先提出结论，再开始推导）、卖关子（留下悬念，并在推导过程中逐步揭开）、转换视角（从读者的视角出发展开推导）、或者是先提出错误结论、指出错误之后再提出正确结论等等。总之，一种结构看多了谁都疲劳，相信你不会希望发生这种事。

　　一个重要的原则是保持语言的多样性，即尽量避免重复的词句出现，哪怕是专业术语，也应该尽量改变描述方法，或者干脆用句子结构上的调整来规避提及术语的必要，从而减少重复。请注意，由于我们所要教授的领域主要是“理科”，专业性和准确性仍然是非常重要的，因此请不要用会令人产生误会的说法。在有确切术语的情况下，你应该在其第一次出现时对它进行强调，让人明白这是用于描述这件事的最专业、最确切的词汇，而不是让人在一大堆描述中自己猜测它的名字。

　　在此，虽然有部分人对此相当反对，但我个人并不讨厌“充满修饰语的名词性结构”，比如“一个logo主色调为蓝色的、以问答为主要形式的、以中文为主要语言的社交网站”。如果说你反对这种用法的原因是它不好理解，那我觉得主要是你表述得不好，通过适当地选择修饰词、在合适的位置加入顿号来制造语气停顿，这种用法的可读性还是可以接受的——大部分人的理解能力还没这么差。当然，如果你是因为“汉语西化”之类的原因反对的话，我们可以有空再讨论。

　　这种用法的好处在于它能够让你以一种足够精确的方式去定义一件事物，因为其结构是显然的：最后一个名词代表了其本质，而之前的每个修饰词之间都是相互独立且易于理解的。我一般的用法是在制造感性认识的描述之后，同时抛出这种定义以及其术语（没有的话可以自己造一个，不过请注明这不是通用术语），然后再继续进行细致的解释。

　　另一个原则是教程的语言应当简单易懂，而不是充斥着（故作）高深的词汇和句式，同时我并不摒弃口语化的表述，毕竟这是网络世界，绝大多数读者的态度没有写论文或教科书时那么严肃，而且有很多优秀的教科书也大量使用了口语化的语言。当然，我的一个（坏）习惯是偶尔掺入一些挺书面的表述，作为口语化表述之间的调剂，就像节奏的快慢那样。

　　第三个原则是亲切的口吻，对此我往往喜欢轮流使用第一人称复数（我们）和第二人称单数（你），仅在偶尔讲述个人观点时使用第一人称单数（我）。另一方面，口吻的亲切也要求你以一种“循循善诱”的语气进行表述，其反面是“严厉”、或是“傲慢”之类的，至少你应该尊重你的读者，相信他们是有独立思考能力、乐于且善于学习的人——闻道有先后，术业有专攻，他们并不低你一等。最后，你可以在文中加入一些包袱和笑话，不过这事不能强求，幽默毕竟是一种很稀有的品质，我也不敢说我就做得很好。

　　第四个原则是保持阅读体验的流畅，尽量避免读者反复阅读同一段内容、或者经常翻找之前的部分。当然，考虑到读者的水平不同，这并不总是能很好地达成，但是你应该对自己的文字非常熟悉，并且经常在引用到前文的地方主动做出解释，而不是等读者主动意识到自己没看懂。常见的做法是加入“XXX，也就是之前提到的XXX”这样的语句，或者“还记得前面说的XXX吗？在这里我们再次看到……”之类的。

　　流畅体验的另一个要求是维持句子和句子、段落和段落之间的连接，主动发现既存的联系，并以连接词、代词等形式表达出来。比如“另一个”这个词就是一个很好的例子，它告诉读者现在所读到的这一句/段和之前是并列关系。哪怕两句/段之间没有什么太重要的关系，你仍然可以使用一些通用的连接词，比如“接着”、“另一方面”、“还有”、“我们还会看到”之类的。不过，也并不是每两句/段之间都必须得有连接，在合适的时候用分割线之类的直接打断也是一种不错的选择，也能保持措辞的多样性。

　　还有一个有趣的用法是使用括号，即括号内加或不加都能维持句子的阅读，比如“（故作）高深”，以及语句中内嵌的链接，比如“我们可以”。后一种用法又能够衍生出一些高级用法，比如使“这三篇文章”中的“这”、“三篇”和“文章”分别指向三篇不同的文章。总的来说，它们都旨在在不影响阅读流畅性的前提下嵌入附加的信息，更多的用法这里限于篇幅就不多赘述，待读者们（或者说作者们）自己积累吧。

　　最后一个原则是充分利用形式上的可能性，比如加粗、引用、代码段、主/副标题之类的，这些形式自带的表达效果会很大程度上影响读者的阅读体验。很多人都会忽略的是（有序）列表，往往选择自己用“1.”、“2.”这样的文字模拟出列表的格式来，然而绝大多数文字平台实际上都支持列表，其自带的格式一般而言也比自己模拟的阅读体验要好不少。

　　当然由于现存的大部分文字排版系统都并非为中文（或者日语等）而专门设计的，因此在中文表达时多少有些不足，比如缺少西文中斜体的对应（虽然中文也可以用斜体但是我个人很反对，一个合适的对应是使用仿宋字体，不过绝大多数平台都不支持改字体）、中英文混排效果很差、中文嵌入代码段的对齐问题等。

　　这里可能很多是我作为（准）设计师的碎碎念，不过一些比较注重排版的自媒体也多少注意到了这些问题，比如少数派上有一篇不错的文章介绍了他们的排版规范，当然这不是唯一的做法，也不一定就是最好的，不过其背后的思想仍然是值得我们学习的。重要的是，无论是哪种规范，用法要统一、排版要美观、充分利用平台的排版功能，这几点总是没错的。

　　最后还有我的（可能也是很多程序员博主所共有的）几个小癖好，为什么要这么做，我自己也说不出个所以然来，感兴趣的读者可以自行调查一下：