V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
这是一个专门讨论 idea 的地方。

每个人的时间,资源是有限的,有的时候你或许能够想到很多 idea,但是由于现实的限制,却并不是所有的 idea 都能够成为现实。

那这个时候,不妨可以把那些 idea 分享出来,启发别人。
ech0x
V2EX  ›  奇思妙想

现在网上有非常多的「教程」,那么什么是好的教程呢?

  •  1
     
  •   ech0x · 2020-01-02 20:35:37 +08:00 · 6356 次点击
    这是一个创建于 1786 天前的主题,其中的信息可能已经有所发展或是发生改变。

    RT

    如今你想在网上学某样东西,你基本上都可以搜到对应的教程,但是这些教程有好有坏,我们基本上凭借直觉在分辨一个教程的好坏,坏的教程会误导人浪费人的时间,好的教程可以让学习者事半功倍。但是究竟什么样子的教程算得上好的教程呢,或者说好的教程具有什么样子的特征呢?

    我觉得我们应该思考一下这个问题,思考这个问题不仅可以帮助读者寻找一份高质量的教程,也可帮助作者创作出一份高质量的教程。

    那么在诸位的心中什么样子的教程是一个好的教程呢?

    37 条回复    2020-01-05 10:23:55 +08:00
    locoz
        1
    locoz  
       2020-01-02 21:07:15 +08:00
    个人认为,一个好的教程至少要保证逻辑清晰、内容明确、表述无歧义这三点。
    (其实很多写“教程”的人连逻辑清晰都做不到,特别是一些 CSDN、博客园上的文章...逻辑极其混乱,一会儿讲这个一会儿讲那个,然后核心部分又理不清,属于典型的写了还不如不写的类型
    ma836323493
        2
    ma836323493  
       2020-01-02 21:26:16 +08:00 via Android
    按照金字塔原理写的文章,看下腾讯或者美团一些大厂的技术公众号,感觉都有深度且易理解,或者阮一峰或左耳朵耗子
    cvbnt
        3
    cvbnt  
       2020-01-02 21:40:57 +08:00 via Android
    条理清晰是最基本的,我理解很多人写代码很喜欢写注释,但如果是中文教程里步骤和注释混杂写在一起对看的人就是灾难,更有甚者会补点感动自己的心灵鸡汤,这种只能称之为个人随笔,在我看来好的教程至少要有:
    1,步骤分段标序号(方便提问者提问)
    2,步骤注释用不同字体或者括弧补充
    3,尽量不写和教程无关的东西
    cmdOptionKana
        4
    cmdOptionKana  
       2020-01-02 21:41:15 +08:00
    golang 的 blog,真正做到了深入浅出,优秀到无与伦比。
    Justin13
        5
    Justin13  
       2020-01-02 21:44:04 +08:00 via Android
    看微软的出的教程你就知道什么叫做好的教程了
    1O
        6
    1O  
       2020-01-02 21:44:59 +08:00
    引人入胜
    garlics
        7
    garlics  
       2020-01-02 21:56:05 +08:00 via Android
    廖雪峰和阮一峰那样的
    Sapp
        8
    Sapp  
       2020-01-02 23:22:02 +08:00
    其实好的教程我感觉大多数都是在自己的博客里写的,类似于掘金、专栏、csdn 里面个人感觉大多数都不怎么样,但是个人博客就存在一个很难解决的问题,除非你是阮一峰那个级别,搜索权重很高,不然你是很难找到他们的,往往是偶尔搜索一些问题从他们那里获取答案才发现这个人写的不错。
    至于怎么算写的不错呢,我觉得大概有这几点,首先是要格式清晰,不能代码直接当文本粘贴,不然阅读起来太费劲了,你甚至都很难搞清楚他写的什么东西。其次逻辑要有条理,能让人顺着思路一步步摸清楚,不能跳跃幅度太大,也不能太过于啰嗦。然后就是文章要有深度,不能简单地一句话解决了问题然后就结束了,最好是能顺着这个问题讲清楚整个流程,比如按系列讲解某一个方向的方方面面,达到知其然也知其所以然的结果。最后就是写的文章最好不要拘泥于某个问题本身,要有自己对于事情更为深度的思考。
    QUIOA
        9
    QUIOA  
       2020-01-03 00:40:50 +08:00 via Android   ❤️ 1
    编程随想那样的
    green15
        10
    green15  
       2020-01-03 01:21:59 +08:00 via iPhone   ❤️ 10
    国外那把人当傻子一样教的教程最好,具细无遗,你学习会联想到的问题在教程中都能直接找到答案,不用再去另外耗费精力找答案。
    很多人写教程潜意识是认为读者这也会那也会,最后写出来的只是面对自己的总结,而不是他人的教程。
    dji38838c
        11
    dji38838c  
       2020-01-03 01:51:41 +08:00
    中文的就很少有好教程
    momocraft
        12
    momocraft  
       2020-01-03 02:18:03 +08:00
    容易重现
    不失真 (简化可以接受, 但不能把人带到沟里)
    falcon05
        13
    falcon05  
       2020-01-03 02:29:01 +08:00 via iPhone
    好的教程应该是准备充分,了解受众群体,油管有很多老外的编程系列教程做得挺好的,逻辑清晰,简单明了,而且还持续更新,不像国内某些教程啰哩啰嗦,半天说不到点子上。
    dawn009
        14
    dawn009  
       2020-01-03 04:01:29 +08:00
    @green15 #10
    @falcon05 #13

    是的。这些写作训练本应当在中学时代传授给学生,可惜作文课给教成八股文了。
    BiteTheDust
        15
    BiteTheDust  
       2020-01-03 07:24:00 +08:00
    好的教程至少格式整洁有调理,该用 LATEX 的用 LATEX,该用代码展示框的用展示框吧
    q8164305
        16
    q8164305  
       2020-01-03 09:00:46 +08:00 via Android   ❤️ 1
    国内很多教材最大的问题是忽略上下文和思维跳跃,如果你只是写给自己看的当然可以忽略,但是用户会看的一脸懵逼
    SakuraOjosama
        17
    SakuraOjosama  
       2020-01-03 09:10:49 +08:00
    好帖子共性☞由浅入深剖析问题 //
    帖子界毒瘤——复制粘贴,排版混乱,机器翻译,通篇代码,发帖感想,谈人生,谈自身缺陷(劳资来找教程,谁稀罕你这辣鸡鸡汤),或大幅前言谈天谈地谈神仙,然后最后一条代码草草结束
    Virace
        18
    Virace  
       2020-01-03 09:28:45 +08:00 via Android
    这东西感觉还看自己,你觉得这个教程你能看懂,之后还能理解举一反三,那这个对你来说就是好教程!另一个吹的再好,再多的人来宣传,看几分钟看不下去别是白扯!
    locoz
        19
    locoz  
       2020-01-03 10:18:06 +08:00
    @Sapp #8 然而绝大多数的博客都是随笔...逻辑比发在其他平台上的文章更加混乱;少部分写得好的一般也都会在其他平台有发布或者被人转载,所以其实搜索权重这个真不是啥大问题。
    locoz
        20
    locoz  
       2020-01-03 10:24:33 +08:00
    @green15 #10
    “你学习会联想到的问题在教程中都能直接找到答案”
    这种教程会太细了,篇幅过长,很多人跟我反映过这个问题。个人觉得还是要视情况而定。

    像有些本身内容就是讲原理、拓展知识面的教程,做得很细没问题;
    但是如果是内容偏实用的教程,这么做就会显得很啰嗦了,细节部分直接引导到别的教程(比如就提一下关键词)反而更好。
    Dex7er
        21
    Dex7er  
       2020-01-03 10:43:19 +08:00
    有种东西叫做,知识的诅咒。。。作者讲的东西,很多都有背景知识,他自己知道也就默认读者都知道,但是很多读者是真的不知道,所以。。。公认的好的教程大概就是由浅入深的废话比较多的奥莱丽的那种吧。。。
    MrOange
        22
    MrOange  
       2020-01-03 11:37:54 +08:00
    如果是程序相关的话,有基础概念,有实例,逻辑连贯。
    no1xsyzy
        23
    no1xsyzy  
       2020-01-03 13:03:24 +08:00   ❤️ 1
    自顶向下(或称倒金字塔)
    (*)(= #3-1 )可精细引用
    (*)(针对 #21 )标明至少两个候选前置(“本教程将假定读者拥有 XX 方面的知识,如果对这方面没有相应知识的,请先阅读《 YYY 》或《 ZZZ 》”)
    给出后续书目(“如果想要深入了解 XX 方面,可以参考《 YYY 》”)
    (*)可机械地复现
    如果有可拓展的部分,内链 > 脚注 > 展开
    (*)(≈#20 )搞清楚自己是:给大众读的 “科普” OR 领进门的 “入门” OR 针对某一话题深入的 “专精”
    对于自己不甚明了的,明确指出自己不甚明了,而不是 “可能……可能……”
    没有错别字
    排版良好

    其中,标记星号的行是特定于 “教程” 的,不带星号的行是针对 “所有非文学” 的。
    no1xsyzy
        24
    no1xsyzy  
       2020-01-03 13:23:23 +08:00   ❤️ 1
    @no1xsyzy 我似乎写了个《关于如何写教程的教程》,但却违反了 2.
    因为是残篇所以不符合 1.、3.、4. 应该没啥问题
    修正:
    5. 应仅指 “操作步骤”
    6. 中 “内链” 应为 “链接”
    10. “排版良好” 应为 “排版正确”
    添加 11. 应选用可以编辑的平台(比如在 V2 就不好),但在编辑时应保留编辑记录( Change log ),尤其删去列表内一个条目时应保留该条而添加删除线并声明其错误,避免引用的混乱(整章节删除时可删除其正文和下属子标题,但应保留章节标题加删除线,并添加一个子标题 “删除原因” ,后续正文声明整段删除的原因)。
    no1xsyzy
        25
    no1xsyzy  
       2020-01-03 13:32:03 +08:00
    不过看回复好像很多人说的是 “如何写”,而不是 “如何分辨” [1]
    分辨的话大概采用 1. 3. 4. 就行了

    说道如何写,想起某个钱学森被下药忘记所学、结果靠笔记全部给找回来的都市传说
    不妨想象着 “假如我有天失忆了,我能靠这个重新掌握我所知的一切吗?” 来写

    [1]: 当然,我承认我 #23 也有点这样
    no1xsyzy
        26
    no1xsyzy  
       2020-01-03 13:33:17 +08:00
    不过,警惕 Goodhart 定律:当任何措施本身成为目标时,它便不再是好措施。
    PbCopy111
        27
    PbCopy111  
       2020-01-03 13:52:44 +08:00
    首先,要看日期。。。。我经历过好几次看着教程学习,到最后发现是过时的东西。。。
    drawstar
        28
    drawstar  
       2020-01-03 14:02:37 +08:00
    详细,越啰嗦越好
    userdhf
        29
    userdhf  
       2020-01-03 15:06:03 +08:00
    1. 用词要书面化和严谨,
    2. 要有对专业名词的解释附录
    3. 要将技术原理和相关涉及讲清楚
    4. 有简单易懂或者贴近开发的代码、注释
    wsx001
        30
    wsx001  
       2020-01-03 18:23:00 +08:00
    找本书看比看博客要好点,写博客的人水平层次不齐,鱼龙混杂,而出名的书往往就那么几本,里面很有可能会有你想要的答案
    wangxin13g
        31
    wangxin13g  
       2020-01-04 09:24:13 +08:00
    如果是具体技术就是官方手册,如果是非具体技术 比如编程范式这种,非 CSDN 掘金 博客园 简书 知乎这种低门槛网站的可能比较好
    crclz
        32
    crclz  
       2020-01-04 11:10:07 +08:00
    官方文档,例如微软的 docs
    ysyk
        33
    ysyk  
       2020-01-04 20:49:48 +08:00
    看你是想要什么了,有的是 step by step,有的是立即解决问题。
    两种场景是不一样的。
    新学一个东西时,想要的是 step by step。
    使用中,遇到问题,想要的是立即解决问题,FAQ 等。
    没有好坏,只是你正好遇到错误的“教程”。
    no1xsyzy
        34
    no1xsyzy  
       2020-01-04 21:16:46 +08:00
    @ysyk 如果一个 “step by step” 的教程添上一个便利的搜索功能,可能符合 80% 的 “立即解决问题”
    我甚至见过纸质书,前面有分门类的目录,后面有 A-Z 目录,把所有术语列出来,想要立即解决问题时可以迅速找到。除此以外,List of (Diagrams/Tables/Listings) 也是很有帮助的东西。
    ysyk
        35
    ysyk  
       2020-01-04 21:28:16 +08:00
    @no1xsyzy 你说的很完美。
    你指的这种,很类似大英百科全书。

    但现实是很多工具、框架、编程语言,是在用爱发电,没有那么多精力去维护一份完美文档教程。

    有很多时候,不是所用的工具 /框架 /编程语言出了问题,而是运行环境问题,那应该是提供工具 /框架 /编程语言的人或组织去维护解决运行环境的问题,编写教程?这个时候就需要确定教程的范围。

    docker 的流行,从侧面反映了上面描述的问题。

    提供工具 /框架 /编程语言的人或组织,嫌弃那些经常出现环境问题重复,就打包一个标准化镜像。
    instruction
        36
    instruction  
       2020-01-04 23:13:29 +08:00
    先推荐一些非常基础的书藉看完,之后再配合书藉简明易懂的增添去伪的讲解之后再加以实例说明,,,,大概这种?
    daimubai
        37
    daimubai  
       2020-01-05 10:23:55 +08:00
    那就是不要只看一个教程,结合看,我学习技术是:经典视频快速过一遍-> 最少两本书籍(主要加强印象和概念) -> 再看一遍视频(实战) -> 找题或者撸功能 -> 做笔记,写博客 完了
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2588 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 05:03 · PVG 13:03 · LAX 21:03 · JFK 00:03
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.