V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
KalaSearch
V2EX  ›  分享创造

我写了一篇《给程序员的中文写作指北》

  •  5
     
  •   KalaSearch · 2020-07-06 13:30:45 +08:00 · 13962 次点击
    这是一个创建于 1361 天前的主题,其中的信息可能已经有所发展或是发生改变。

    看到有很多 v2 小伙伴都在写博客,而我之前也是博客(搭建)大军里的一员。时间都用在搭 wordpress 上了,真正的输出没多少。最近静下心来,结合之前在知乎写答案的经验,写了一些文章

    我发现中文世界里有关程序员写作的教程类文章非常少,但其实写作对程序员非常重要。

    • 如果你在大厂,升职加薪可能不光靠代码,还需要写合格的设计文档
    • 如果你在创业,需要写内容来吸引用户的话,就更不用说了。
    • 哪怕你只是业余写定博客,写出好的文章也是你树立个人品牌,吸引读者从而促使你长期坚持的必要条件。

    于是,我写了这篇

    => 《给程序员的中文写作指北》

    从内容、排版和行文三个角度,给出了一些给程序员的中文写作“指北”建议

    我自信,如果你能按其中的建议坚持,结合你自己的实践,很快就可以开始写出丰满且吸引人的内容。希望能帮到同样需要写作的你们

    文章比较长,建议收藏后慢慢看完。如果你也写博客的话,不妨在回复里留下你的博客链接,我们互加个友链吧!

    以下是前言,全文请到移步: https://kalasearch.cn/blog/writing-guide-for-programmers/

    作为一名程序员,我们的本业让我们绝大多数的时间都在埋头写代码。

    但很多时候,不管你在自己创业还是在公司搬砖,光是代码漂亮是不够的。很多时候,特别是当你需要展示你的想法或者说服别人的时候,好的文章、设计文档至关重要。

    比如说,如果你在公司搬砖,在新做一个稍大型一点的系统的时候,设计文档写得怎么样可能直接关系这个项目是不是会被孵化。而如果你在自己创业,能写出好内容则更加重要——毕竟你要说服陌生人购买你的产品、使用你的服务,首先你的潜在用户需要通过你的清晰表达来了解你在做什么,你的产品能帮他们解决什么问题。

    就算你对写风花雪月不感兴趣,那你总得偶尔写一些技术文章、交接文档。就算纯技术相关的内容,也需要刻意地练习,才能写得清楚漂亮。不知道你有没有注意过,多数优秀的项目不光代码优秀,文档也非常棒。这里说的漂亮不光是排版规整,行文也流畅且自然。

    不幸的是,作为程序员的我们,一旦文章不漂亮,第一直觉想起来的事不是调整文章,而是调整 CSS 和页面布局。页面怎么摆固然重要,但文章本身如何,才是根本。毕竟你的读者都是人,而不是读 html 的计算机。

    之所以我把这篇文章标题起为“给程序员中文写作指北”,是因为两个原因

    我自己是程序员,我也不知道怎么写小说,但技术文章我写了不少。因此我的观点只适用于程序员群体 “指北”而非“指南”是因为这些也只是我自己的经验总结,不同人肯定有不同的意见。而太主观的观点在我看来,不适合写一份“指南”作为黄金标准 正因为此,如果你读到与自己习惯完全相左的内容,不用担心,也许那样的习惯更适合于你。但总体上,有一些放诸四海皆准的原则,比如段落不宜太长,比如不要中英标点混用等等。总之,希望大家各取所需,根据自己情况调整就好。

    余下全文: https://kalasearch.cn/blog/writing-guide-for-programmers/

    第 1 条附言  ·  2020-07-17 13:43:56 +08:00

    非常非常欢迎v友们来换友链,请把需要换的友链加到回复中(网址和锚文本)

    请把 https://kalasearch.cn 和锚文本“卡拉搜索” 加到你的友链中,即: 卡拉搜索

    69 条回复    2020-08-05 13:04:53 +08:00
    JiangTianZheng
        1
    JiangTianZheng  
       2020-07-06 13:56:41 +08:00
    居然不知不觉看完了。比李笑来老师的写作课更贴近码农。

    发现了宝藏站,收藏了。
    kdwycz
        2
    kdwycz  
       2020-07-06 14:28:10 +08:00
    博客不错,希望能支持下 rss 订阅
    KalaSearch
        3
    KalaSearch  
    OP
       2020-07-06 15:36:30 +08:00
    @kdwycz 感谢!

    好的,尽快搞一下,你的博客也有 rss 吗?
    KalaSearch
        4
    KalaSearch  
    OP
       2020-07-06 15:36:45 +08:00
    @JiangTianZheng

    谢谢!
    storypanda
        5
    storypanda  
       2020-07-06 15:40:50 +08:00 via Android
    @KalaSearch 我的博客也有 rss
    KalaSearch
        6
    KalaSearch  
    OP
       2020-07-06 15:46:36 +08:00
    @storypanda 赞!大佬换链吗?
    storypanda
        7
    storypanda  
       2020-07-07 03:24:53 +08:00 via Android
    KalaSearch
        8
    KalaSearch  
    OP
       2020-07-14 12:30:45 +08:00
    raaaaaar
        9
    raaaaaar  
       2020-07-17 12:37:18 +08:00 via Android
    多分段,和段落间空一行
    KalaSearch
        10
    KalaSearch  
    OP
       2020-07-17 12:39:40 +08:00
    @raaaaaar 好建议,段落长度也有讲究
    SteveZou
        11
    SteveZou  
       2020-07-17 12:51:23 +08:00 via Android
    很有用
    becauseOf
        12
    becauseOf  
       2020-07-17 12:54:55 +08:00 via Android
    已收藏
    kop1989
        13
    kop1989  
       2020-07-17 13:05:50 +08:00
    赞了,非常棒
    AllenHua
        14
    AllenHua  
       2020-07-17 13:20:08 +08:00
    很棒 谢谢楼主赐教

    可以加个友链吗 (我今晚 23:59 分之前加你的)

    Allen Hua Site: https://hellodk.cn
    swieer
        15
    swieer  
       2020-07-17 13:25:01 +08:00
    指北比指南逼格高点吗
    KalaSearch
        16
    KalaSearch  
    OP
       2020-07-17 13:36:59 +08:00
    @AllenHua 好的,加上以后请 ping 我,我会第一时间链到 https://hellodk.cn/
    KalaSearch
        17
    KalaSearch  
    OP
       2020-07-17 13:37:33 +08:00
    @swieer 没有,文章里有写,主要是会有主观意见所以不好意思指南
    alpha4zeta
        18
    alpha4zeta  
       2020-07-17 13:39:16 +08:00
    楼主可以加下友链吗, 我的站点:
    KalaSearch
        19
    KalaSearch  
    OP
       2020-07-17 13:41:48 +08:00
    @alpha4zeta 你的站点好像打漏了 T_T
    alpha4zeta
        20
    alpha4zeta  
       2020-07-17 13:42:20 +08:00
    楼主可以加下友链吗, 我的站点:
    Herbert's Blog: http://blog.herbert.top/
    已经加上了你链接~
    alpha4zeta
        21
    alpha4zeta  
       2020-07-17 13:50:30 +08:00
    @KalaSearch 🤦‍♂️好久没发回复, 已经补上站点了~
    KalaSearch
        22
    KalaSearch  
    OP
       2020-07-17 13:58:18 +08:00
    AllenHua
        23
    AllenHua  
       2020-07-17 14:04:15 +08:00
    @KalaSearch #22 一定一定
    barrysn
        24
    barrysn  
       2020-07-17 14:32:02 +08:00
    @KalaSearch 我觉得大多数技术人员的最大的写作问题是,因为 “知识的诅咒”的原因,讲不清楚自己想要表达的东西
    KalaSearch
        25
    KalaSearch  
    OP
       2020-07-17 14:36:44 +08:00
    @barrysn 第一次看到这个词,搜了下,很有意思,感谢

    是的,很多时候我写文章要反复跟自己强调:如果需要读的面广的话,需要把 context 讲清楚

    即使写论文的时候也有个 introduction 嘛 :)
    berrx
        26
    berrx  
       2020-07-17 15:21:13 +08:00
    关于标点符号这个, 因为方便写代码我把电脑设置成默认英文标点了, 但是这样会让标点符号看起来不明显, 我的做法一般是在英文标点后再加一个空格这样...
    YvesX
        27
    YvesX  
       2020-07-17 15:22:14 +08:00
    技术文章不是文章,甚至可以说,科学写作与文学创作在许多方面根本背道而驰。
    中文技术文章以面无表情为乐趣,副词连副词,克制加克制,许多根本就是结构一泡污的文档。
    shaopu
        28
    shaopu  
       2020-07-17 15:38:51 +08:00
    仔细看了下,我现在写作的风格好多跟楼主写的一样
    AllenHua
        29
    AllenHua  
       2020-07-17 15:42:02 +08:00
    @KalaSearch #22 楼主,已加你的哦 https://hellodk.cn/friends-sites
    lazyyz
        30
    lazyyz  
       2020-07-18 10:51:11 +08:00
    看了大佬的文章,我觉得是时候把自己吃灰的博客捡起来了
    KalaSearch
        31
    KalaSearch  
    OP
       2020-07-18 10:56:59 +08:00
    @lazyyz 过奖了

    多写写博客对程序员职业生涯的确有帮助,快捡快捡 :D
    bigyezi
        32
    bigyezi  
       2020-07-18 12:26:56 +08:00 via Android
    感谢楼主
    AFuture
        33
    AFuture  
       2020-07-18 14:14:43 +08:00 via iPhone
    内容受教了。
    Soar360
        34
    Soar360  
       2020-07-20 15:00:15 +08:00
    https://www.coderbusy.com/
    码农很忙
    大佬多多指教
    KalaSearch
        35
    KalaSearch  
    OP
       2020-07-20 15:11:14 +08:00
    @Soar360 已加,正在 build,大概 15 分钟之后可以看到了。

    请帮忙加上 卡拉搜索 链至 kalasearch.com
    Soar360
        36
    Soar360  
       2020-07-20 15:19:50 +08:00
    woostundy
        37
    woostundy  
       2020-07-20 20:46:30 +08:00
    博客很棒。
    KalaSearch
        38
    KalaSearch  
    OP
       2020-07-21 00:33:00 +08:00
    @woostundy 感谢<3
    scnace
        39
    scnace  
       2020-07-21 00:52:30 +08:00 via Android
    有写给程序员的 PPT 制作指北嘛(逃
    KalaSearch
        40
    KalaSearch  
    OP
       2020-07-21 01:08:28 +08:00
    @scnace 做 PPT 不光要会讲故事了,还得审美强。后者我差了一截,没法写 T_T
    kios
        41
    kios  
       2020-07-21 09:59:47 +08:00
    感谢分享
    cnrting
        42
    cnrting  
       2020-07-21 10:20:39 +08:00 via iPhone
    这是个月经推广贴🙃
    zlu1123
        43
    zlu1123  
       2020-07-21 10:28:10 +08:00
    先马后看好习惯
    KalaSearch
        44
    KalaSearch  
    OP
       2020-07-21 11:18:39 +08:00
    @kios 不客气 <3

    @cnrting 写篇好文章不容易,不推广可惜了

    @zlu1123 给你的习惯点赞
    warush
        45
    warush  
       2020-07-21 12:23:10 +08:00 via iPhone
    大佬带一下:warush.club
    KalaSearch
        46
    KalaSearch  
    OP
       2020-07-21 13:17:17 +08:00
    @warush 好的,请帮我把“卡拉搜索”加到你的友链呀

    你需要什么锚文本? WA Rush? 我晚上一定加一下

    搞 ACM 的看你这 ID 要笑出声
    graetdk
        47
    graetdk  
       2020-07-21 13:51:23 +08:00
    卡拉搜索,我提交申请试用,貌似返回了一个 404 ?
    KalaSearch
        48
    KalaSearch  
    OP
       2020-07-21 13:52:27 +08:00
    @graetdk 表单处理没搞好,但已经收到了你的申请啦。很快跟你联系 <3
    graetdk
        49
    graetdk  
       2020-07-21 13:56:35 +08:00
    @KalaSearch 期待期待!
    fenx
        50
    fenx  
       2020-07-21 14:10:03 +08:00
    博客最近更新位置还以为是目录……
    zcxey2911
        51
    zcxey2911  
       2020-07-21 17:19:15 +08:00
    @KalaSearch 刘悦的技术博客 https://v3u.cn 已经添加贵站
    KalaSearch
        52
    KalaSearch  
    OP
       2020-07-22 13:21:48 +08:00
    @zcxey2911 好哒,已加
    encro
        53
    encro  
       2020-07-22 15:11:41 +08:00
    rss 链接是错的,打不开。。。
    encro
        54
    encro  
       2020-07-22 15:13:01 +08:00
    https://www.kalasearch.cn/blog/blog/how-to-name-your-startup/

    rss 里面的内容是这样,正确的应该少一个 blog
    xrr2016
        55
    xrr2016  
       2020-07-22 16:15:11 +08:00
    受教了,谢谢。已添加友链 https://coldstone.fun/
    Kirsk
        56
    Kirsk  
       2020-07-22 23:30:44 +08:00 via Android
    附言过于真实 论程序员如何有效的营销自己
    KalaSearch
        57
    KalaSearch  
    OP
       2020-07-23 00:35:24 +08:00
    @xrr2016 链回了,你的博客很赞,文章清晰配图也非常美观
    KalaSearch
        58
    KalaSearch  
    OP
       2020-07-23 00:37:03 +08:00
    @encro 啊!感谢你的发现!上次改了网站没有改 rss,一会改一下 <3
    imn1
        59
    imn1  
       2020-07-23 20:44:10 +08:00
    @swieer #15
    指南通常是“正向引导”,指北是“逆向引导”
    逆向不是引导错误的意思,而是指出错误达到引导正确的目的,意思就是纠正、勘误
    如果换一种现在常见的说法就是《程序员的中文写作的误区》

    还没看文章,不知道是否这个,但指北是这个意思
    WytheHuang
        60
    WytheHuang  
       2020-07-23 21:01:42 +08:00 via Android
    收藏了
    imn1
        61
    imn1  
       2020-07-23 21:47:07 +08:00
    看完了,说些个人看法

    程序员写博客,应该说明文占了绝大多数比例,论文其次,其他文体除非有个人爱好不然比例很小
    说明文主旨明确这个就不用说了,是必须的,在易读性方面比较重要的是说明顺序

    LZ 此文建议“总分总”,但其实还有很多其他顺序可用
    程序员的话,可以把写文章顺序想象成一个代码的设计模式
    抽象类、接口就是前言、index
    如果写一次出错及解决,就是单例
    如果写安装过程,工厂模式,1234 怎么做
    如果写项目的架构,建造者模式 /责任链模式,1234 各实施什么职责
    如果写权限分析,适配者模式,就不要 1234 而是圆点列表
    ……

    当然,正如 “设计模式不是固定的” 那样,写作顺序也不是唯一,同一个问题,切入点不同顺序也可以多样

    见过一些文章非常详细记录了自己的纠错过程,这些文章适合自己(备忘录),但不太适合别人
    大多数人不太关心笔者走过的弯路,简略带过指出“此路不通”或者“治标不治本”就行了,正确解决方案最重要
    当然不排除少数人很有耐心看完全过程,这些往往是探究中间弯路为何不通的人,如果确实想全记录,建议把最后正确处理的步骤加粗显示,有点像前置;TLDR 的意味
    0xABCD
        62
    0xABCD  
       2020-07-26 16:58:06 +08:00 via Android
    原来你就是给我发垃圾邮件的那个人......
    twoconk
        63
    twoconk  
       2020-07-26 18:06:09 +08:00
    现在还停留在写使用手册级别,确实需要提升!
    wobuhuicode
        64
    wobuhuicode  
       2020-07-26 18:58:50 +08:00
    现在的技术文章起名就是:
    标准买课类的:XX 天学会 XXX or 从零开始的 XXX
    推广类的:XXX 技术指北 or 当我们讨论 XX 的时候在讨论什么 or
    user919lx
        65
    user919lx  
       2020-07-27 12:36:07 +08:00
    我也经常写技术文章,基本按照楼主的要求来的,确实写下来之后很受好评。大家都觉得写得清晰易懂,这也为我的跳槽提供了很大的帮助。

    不过想问问楼主,有没有什么保持持续创作,或者降低时间成本的办法。我平时收集了大量的实践经验素材以及前人的各种总结经验,但一到下笔的时候还是会感觉很吃力,有前面的积累,要写出很多东西并不难,我能用四五个小时写到七千字,但关键是如何把内容收束到主题下,有时候写着写着就觉得自己写得太多了,但是要删掉又怕上下文不完整之类的。我在细节上的解释总是不厌其烦,而这样反复的修改乃至删减花费了我大量的时间,一篇文章从动笔到完成,得花上 10 ~ 20 小时,由于写作非常需要连贯的时间,所以对日常生活也是很大的负担。 就是想了解有什么技巧,能缩短时间,或者把零碎的时间利用起来,毕竟我也不想把一整个周末都拿去写一篇文章,那太累了。
    KalaSearch
        66
    KalaSearch  
    OP
       2020-07-27 13:31:34 +08:00
    @user919lx

    看来你已经非常厉害了,能四五个小时写七千字,已经说明你对写的主题理解非常深,下笔有神。

    对于如何收得住主题这个问题,我通常会先把提纲列好,不在提纲内的内容不写。在下笔前我会确保提纲已经写好了,而且提纲就是 h2 和 h3 :D
    redeyesovo
        67
    redeyesovo  
       2020-08-05 11:42:11 +08:00
    看到个错字,在 #动笔前先把想法理清楚 的 “逻辑必须自恰,这样才能做到讨论的时候言之有物。” 这一句里。
    KalaSearch
        68
    KalaSearch  
    OP
       2020-08-05 12:17:09 +08:00
    @redeyesovo 感谢 <3
    XBlackBerry
        69
    XBlackBerry  
       2020-08-05 13:04:53 +08:00 via Android
    很赞!
    之前也写过一篇关于排版和写作规范的文,不过不是针对技术同学😂
    设计|从设计的基本原则谈公众号排版: https://mp.weixin.qq.com/s/vuiEjhLNbMIixlYnzCGj_A
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1016 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 30ms · UTC 19:41 · PVG 03:41 · LAX 12:41 · JFK 15:41
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.