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

如何提升编写文档能力

  •  1
     
  •   linksyi18 · 2022-02-05 23:53:15 +08:00 · 4959 次点击
    这是一个创建于 782 天前的主题,其中的信息可能已经有所发展或是发生改变。

    java 码农一枚,三年多经验,最近新入职一家公司,被说项目文档写的很差,想问大家是如何提升文档编写能力的,有相关的数据或者文章推荐吗

    32 条回复    2022-02-08 00:10:37 +08:00
    maocat
        1
    maocat  
       2022-02-06 03:09:44 +08:00 via iPhone
    优雅,命名规范的代码就是最好的文档 手动狗头
    Mac
        2
    Mac  
       2022-02-06 03:57:59 +08:00 via Android
    你是要学行文的风格?那建议学一下写公文。
    israinbow
        3
    israinbow  
       2022-02-06 05:02:40 +08:00 via Android
    接口文档是模板生成,至多自己写几句介绍和注意事项,这些内容只要尽可能简洁明确的表达意图,对于说明性介绍性的文档,面向老板和面向用户的风格也不一样,应用文写作是基础,去学习一下罢。剩下的就是阅读和写作的积累了,简单地说,如果你想让文字强而有力,保持简洁和清晰就足够了。
    israinbow
        4
    israinbow  
       2022-02-06 05:27:20 +08:00 via Android
    @israinbow #3 关于简洁 tldr:不完文字游戏,说人话,不要错别字

    文档是功能性文章,且目的明确(就是为了告诉读者你要干嘛),所以写作的时候注意不要含有过多的修饰、嵌套否定 /肯定、奇怪的网络用语、暧昧的用词、有歧义的地方打注释消歧义、引用的地方标注来源、文字格式和符号运用也要注意,如用 markdown 编辑的时候给编辑器装个 markdown lint 确保你编辑的时候没有换行或层级问题。最后是文字的排版,这个比较主观,大体上就是你写完之后自己多读两遍,优化不通顺的句子,拆分过长的段落。发布前让周围人试读,他人的评价更客观,询问听取建议后再改一改,当然,也要保持自己的见解,盲目修改就变成他人的 ”主观“ 了。
    msg7086
        5
    msg7086  
       2022-02-06 07:30:39 +08:00   ❤️ 2
    我上学的时候有一门课叫 Technical writing 。
    qaqLjj
        6
    qaqLjj  
       2022-02-06 07:37:05 +08:00 via Android
    写短句且多换行
    Hyvi
        7
    Hyvi  
       2022-02-06 08:53:01 +08:00
    你要问下差在什么地方先。再针对性的改进。
    yuezk
        8
    yuezk  
       2022-02-06 09:01:37 +08:00 via iPhone
    @msg7086 受到启发,可以 Google 一下 Technical writing 然后挑靠前的看看
    wangxiaoaer
        9
    wangxiaoaer  
       2022-02-06 10:39:42 +08:00
    注意书面化,避免口语化,另外用词要严谨,起码少用黑话。
    ch2
        10
    ch2  
       2022-02-06 10:43:20 +08:00 via iPhone
    找你觉得好的文档模仿
    byte10
        11
    byte10  
       2022-02-06 10:45:55 +08:00   ❤️ 1
    文档是很简单的东西,写不好说明思维还在技术层面上。作为过来人,我跟你分享下经验。

    关于:听说读写。我就只讲写,写的表达方式有很多种。第一种就是写文档,比如写技术文章等,第二种就是画图表达技术,第三种就是通过动画表达技术。想练习好写文档的能力,首先你多点写技术文档(可以找各种资料然后整合也是可以),然后发给我看,或者发给别人看。如果别人看不懂,说明你写的不好。

    第二种画图,比如技术架构图,系统架构图等,你看看别人怎么画的,然后画一个你公司的技术啥的,给大家看,大家能看懂就说明你画的不错。做动画视频也是一样。

    如果写文档没有思路,那么就记住一点,如何把大象放进冰箱里,能理解这个思路,相信你写文档就不会再有问题。

    关于画图,这个我没有具体可操作的思路教你。

    反正别人听不懂,说明你讲的还不行。参考 费曼学习法。
    xuanbg
        12
    xuanbg  
       2022-02-06 10:48:03 +08:00
    严格按模版写
    BeautifulSoap
        13
    BeautifulSoap  
       2022-02-06 10:57:11 +08:00 via Android
    上上面好多人写文档都没提很重要一点啊:有时候写文档要站在没有接触过你这项目的人的角度来写,如果连领域知识文档都没有后来接手的人看文档等于天书
    balabalaguguji
        14
    balabalaguguji  
       2022-02-06 11:11:42 +08:00
    用一个好的文档工具 https://easydoc.net
    zmxnv123
        15
    zmxnv123  
       2022-02-06 11:28:10 +08:00 via iPhone
    多写博客试试
    YaakovZiv
        16
    YaakovZiv  
       2022-02-06 11:51:06 +08:00
    我是先写后优化,我应该是团队里被吐槽次数最多的了,别人吐槽以后,我就参考别人的文档样式修改我自己的文档。
    文档内容口语化是我当前一大缺陷,已经一年多了,还没改掉。
    面对不同人,写不同文档,如果是同行,就省略掉基础解释。如果给客户写,就要当作教零基础学生写文档。
    目前我被公司内同事夸奖最多的文档,是两份让人看了就懂,无需多加思考的文档,被很多同级别同事称赞认真去写。
    zjp
        17
    zjp  
       2022-02-06 12:13:12 +08:00   ❤️ 6
    konakona
        18
    konakona  
       2022-02-06 15:08:13 +08:00
    强烈安利楼主看一下《活文档》这本书,通过书可以了解有多少种活灵活现的文档展现形式。

    BTW ,我感觉你说你文档写的差,我认为是关键的部分不太行。比如代码展现逻辑、接口顺序、分类归纳、示例健全度等,这些偏向严谨方面的东西做的“很随意”导致的。
    romisanic
        19
    romisanic  
       2022-02-06 15:09:41 +08:00
    不用非得从网上找啥的 你可以问一下这么说你的同事 然后让他把他认为你们内网比较优秀的文档发你看看 模仿着来就行了 写多了就得心应手了
    dingyaguang117
        20
    dingyaguang117  
       2022-02-06 15:27:58 +08:00
    本质还是要考察作者的,归纳整理能力 和 表达能力。

    先用思维导图做好提纲(架构),然后再写细节就行。
    Cielsky
        21
    Cielsky  
       2022-02-06 16:10:06 +08:00 via Android
    功能性文档的话:简洁无二义。先概括功能,再展开论述。
    其他的不清楚
    duke807
        22
    duke807  
       2022-02-06 17:08:53 +08:00 via Android
    先寫大綱,再寫內容
    leafre
        23
    leafre  
       2022-02-06 17:40:20 +08:00
    不来个文档示例,很难看出哪里写得差
    kunkunzhang
        24
    kunkunzhang  
       2022-02-06 17:51:56 +08:00
    这样问比较虚,建议拿出一些范例让大家直接帮你纠正是最好的
    liuliancao
        25
    liuliancao  
       2022-02-06 19:54:47 +08:00
    提下拙见
    1. 了解 markdown 或者 org 等工具,代码着色,分标题,分段落,减少错别字,可以用 docsify 等
    2. 代码的 doc tool ,养成写注释的习惯
    3. 看看他们的文档,多和同事请教下
    vazo
        26
    vazo  
       2022-02-06 21:26:32 +08:00
    《科技文档写作实务》
    wangyzj
        27
    wangyzj  
       2022-02-06 22:38:50 +08:00
    有时间思考就行
    foam
        28
    foam  
       2022-02-06 23:38:49 +08:00
    不知道楼主说的项目文档具体是哪种呢?
    API 文档,能够描述清楚请求响应的参数即可;楼主说的可能是 系统设计、业务逻辑文档。

    写这类专业性文档,有几点要注意的:
    1. 描述清楚上下文。需要用些篇幅来介绍背景、上下文,专业术语。写的时候要代入读者,设身处地思考 TA 能不能看懂。
    2. 逻辑清晰。最好列个大纲,不要想到哪写到哪。多用 1 ,2 ,3 描述步骤或者阐述观点。
    3. 图文并茂。文字难以描述的,务必带上图。

    有兴趣可以看看我的博客。https://foamzou.com
    若楼主有博客也可以贴出来,我们一起学习交流。
    leonme
        29
    leonme  
       2022-02-07 09:31:57 +08:00 via iPhone
    金字塔原理
    dahutu
        30
    dahutu  
       2022-02-07 11:23:24 +08:00
    跟着新闻五要素更改一下就能用。
    是什么:文档是什么方面的
    为什么:文档出现的原因是解决什么的
    什么人:那些人需要文档
    怎么:文档记录问题是怎么解决的
    什么时间:问题什么时候出现的

    然后整理一下顺序,应该就可以了
    dany813
        31
    dany813  
       2022-02-07 13:20:28 +08:00
    学习了,我文档写的也不行
    aguesuka
        32
    aguesuka  
       2022-02-08 00:10:37 +08:00
    试着翻译文档, 如果英语不好可以尝试已有翻译的文档, 或者熟悉语言 sdk 的注释文档
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   994 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 20:05 · PVG 04:05 · LAX 13:05 · JFK 16:05
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.