V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
fiveelementgid
V2EX  ›  程序员

谈谈某些"大佬"说微软 MSDN 文档全面的个人见解

  •  
  •   fiveelementgid · 2020-11-25 00:58:45 +08:00 · 1471 次点击
    这是一个创建于 1219 天前的主题,其中的信息可能已经有所发展或是发生改变。

    仅代表个人看法 MSDN 即为微软的文档 emmmm 上个帖子有人说微软的文档齐全啥的,我来吐槽一下

    结论:微软的文档在我看来只适合用于 demo 尝鲜和当作参考文档,用于已经入门的新手就是噩梦

    证明自己不是云玩家 贴一下证据:

    Screenshot from 2020-11-25 00-45-50.jpg

    混了 MSDN 半个月,帮.net 在文档上面改正了 1 处大错误,1 处语法错误,两处标记 日后看文档的萌新在文档顶部能看到我的 github 头像呢(狗头,我就吹吹牛,大佬们求放过) 先不谈一大堆错误,整个文档只有一个简短的 demo 演示

    在教程中,剩下有用的只有 Fundementals 和 Advanced 部分(里面夹杂了一大堆的 principle 和 design pattern),但是对于刚入门 C#的人来说,难度过大(个人看法) 拥有最全面的 API Reference 不假,但是问题还是很严重,特别是刚入门又没成为高级开发者的中间人员来说 所以说,求求不要再吹文档全面了....中间有一个很大的断层.....

    最后如上一个帖子的 @ladypxy 大佬所说

    微软的文档已经是业界最好的了,没有之一…… 你这都搞不定,真的只能像上面说的,可能不适合这行……

    你您看我适合做这行吗(狗头

    ysc3839
        1
    ysc3839  
       2020-11-25 01:20:37 +08:00
    可能是他们接触了太多垃圾文档。

    我同学最近跟我吐槽,go-redis 的 API 文档 https://pkg.go.dev/github.com/go-redis/redis/v8 就几乎是把所有函数给列了一遍,完全没说每个函数具体作用,参数含义,以及会返回什么错误。

    最近我用到 zlib,去官网看文档 https://zlib.net/manual.html 虽然比上面那个 go-redis 好了些,每个函数都有相关说明,但是仍然比不上微软那样能把参数写清楚。

    不过我个人接触到的大部分文档都是挺好的,在我看来 Linux man page 和 cppreference.com 都能比得上微软文档。
    cnnblike
        2
    cnnblike  
       2020-11-25 01:27:56 +08:00
    你可能是没见过真的差的。文档这种东西,只有越来越击穿下限,回头一看,dotNET 居然还不是最差的,差不多就这个概念
    sneezry
        3
    sneezry  
       2020-11-25 01:36:33 +08:00
    这就是社区存在的意义呀,你把 MSDN 的文档变得更好了,参与的人越多,文档会变得越好。我们平时写文档的时间的确有限,公司也不会专门招人写技术文档
    yexiaoxing
        4
    yexiaoxing  
       2020-11-25 01:39:42 +08:00
    欢迎 lz 继续帮助完善文档 :)
    araaaa
        5
    araaaa  
       2020-11-25 01:47:19 +08:00 via iPhone
    去看看 linux api 文档
    lights
        6
    lights  
       2020-11-25 01:48:47 +08:00 via iPhone
    看过的语言文档不多,cpp csharp python php,我觉得 PHP 的文档写得最好,下面还有留言讨论,甚至有时候能找到最佳实践
    DoctorCat
        7
    DoctorCat  
       2020-11-25 02:36:29 +08:00
    @lights 多年前我也这么觉得,现在也这么觉得,那个 CHM 的手册足以搞定很多事情。
    DoctorCat
        8
    DoctorCat  
       2020-11-25 02:37:38 +08:00
    微软的文档确实业界数一数二了,但是天底下就不可能有完美的文档存在。
    fiveelementgid
        9
    fiveelementgid  
    OP
       2020-11-25 09:40:17 +08:00 via Android
    @ysc3839 Linux 的文档📃确实没得说

    @cnnblike 还有这样的吗。。。。。

    @sneezry 没吧,我看 reviewer 就是 Effective C#和 More Effective C#的作者,好像也有负责写内容

    @yexiaoxing 不了,我跑路了,等我啥时候成为高级工程师再回来啃(狗头
    fiveelementgid
        10
    fiveelementgid  
    OP
       2020-11-25 09:41:57 +08:00 via Android
    @araaaa 看过一次 DNS 的文档,一言难尽,但是 Linux 的 man 确实不错

    @lights php 是世界是最好的语言(狗头

    @DoctorCat 重点是坑还是太多.......
    learningman
        11
    learningman  
       2020-11-25 16:33:01 +08:00 via Android
    别说了,这几天在找上古坑,代码 last commit 13 ywars ago,文档还是 TM 韩文写的,直接去看代码了
    fiveelementgid
        12
    fiveelementgid  
    OP
       2020-11-25 17:23:39 +08:00 via Android
    @learningman 哈哈哈哈哈哈哈,谢谢,有被笑到
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5470 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 08:28 · PVG 16:28 · LAX 01:28 · JFK 04:28
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.