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

如何提高自己的文档输出能力

  •  
  •   cobainlu · 2021-12-09 09:30:54 +08:00 · 3270 次点击
    这是一个创建于 840 天前的主题,其中的信息可能已经有所发展或是发生改变。

    最近因为工作的原因需要经常给甲方一些接口 /数据标准的文档.每次写总觉得自己在代码之外输出这些文档的能力很薄弱,参考了一些开源项目的文档,也没有得到很好地启发,各位 v 友在工作中有遇到这些问题吗?

    14 条回复    2021-12-09 15:46:25 +08:00
    Qsong
        1
    Qsong  
       2021-12-09 09:40:53 +08:00
    一个字,熟能生巧
    WilsonGGG
        2
    WilsonGGG  
       2021-12-09 09:43:39 +08:00   ❤️ 18
    作为 PM ,我的建议就是:
    1. 先找一份标准文档,比方说飞书里面可能有这种模板
    2. 根据习惯和内容密度,给模板删去 /增加一些内容
    3. 然后开始写,写个三五份;写的过程中你会发现很多这个模板不足 /不合适的地方。
    4. 每次写完重新读一遍,看看结构,这里不用太一本正经,就是小小的回顾即可
    5. 等你写完三五份,有了一些感悟和反馈之后,要写啥基本心里有数了
    6. 后面就可以去看一些别人的教程、分享,融入到自己的模板中
    7. 如果你比较讲究,可以开一个文档 /思维导图记录下你自己的文档结构,随取随用

    P.S. 新手最忌讳的就是上来就搞一堆教程,你的脑子里没概念,吃的东西消化不了,很容易越搞越烂。先从最无脑 /普适的开始,练个五六次,结构啊内容啊可以改善的啊,基本有数了,这时候再去看别人的教程,你也能大概知道别人的水平,哪些能用哪些不能。
    kujio
        3
    kujio  
       2021-12-09 09:43:45 +08:00   ❤️ 2
    我们公司的产品文档就像初中生写的说明书,(虽然我也不会写)
    akira
        4
    akira  
       2021-12-09 09:59:54 +08:00
    接口文档只要把接口说清楚就可以了
    star7th
        5
    star7th  
       2021-12-09 10:13:21 +08:00
    你注册一个 showdoc 账户, 然后看看其生成的系统文档示例 https://www.showdoc.com.cn/ 。然后根据模板的框架去描述就好。一般情况下都能明白。特殊业务特殊说明。
    cairnechen
        6
    cairnechen  
       2021-12-09 10:17:03 +08:00
    一个比较好的案例?
    https://stripe.com/docs/api
    waltcow
        7
    waltcow  
       2021-12-09 10:18:12 +08:00
    github copilot
    statement
        8
    statement  
       2021-12-09 10:28:51 +08:00
    肯定是找一份文档改
    keshawnvan
        9
    keshawnvan  
       2021-12-09 11:56:22 +08:00
    写文档考验的是精准表达能力,需要多练一练。
    ila
        10
    ila  
       2021-12-09 12:02:05 +08:00 via Android
    swagger
    461da73c
        11
    461da73c  
       2021-12-09 12:14:34 +08:00
    文档的好坏不是很好评判,有些人写的文档,看着洋洋洒洒,都是长句,读起来非常费劲。有些人写的短句口语化较多,读起来又不太严肃。
    balabalaguguji
        12
    balabalaguguji  
       2021-12-09 12:49:46 +08:00
    用易文档写吧,看看多专业 https://easydoc.net/s/17790664/CZMqMhfW/78558034
    reallittoma
        13
    reallittoma  
       2021-12-09 15:30:07 +08:00
    Github Copilot 是正确答案
    rpman
        14
    rpman  
       2021-12-09 15:46:25 +08:00
    Copilot YYDS
    等着出正式版时打钱了
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2427 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 16:05 · PVG 00:05 · LAX 09:05 · JFK 12:05
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.