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

2021-12-09 09:30:54 +08:00
 cobainlu

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

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

P.S. 新手最忌讳的就是上来就搞一堆教程,你的脑子里没概念,吃的东西消化不了,很容易越搞越烂。先从最无脑 /普适的开始,练个五六次,结构啊内容啊可以改善的啊,基本有数了,这时候再去看别人的教程,你也能大概知道别人的水平,哪些能用哪些不能。
kujio
2021-12-09 09:43:45 +08:00
我们公司的产品文档就像初中生写的说明书,(虽然我也不会写)
akira
2021-12-09 09:59:54 +08:00
接口文档只要把接口说清楚就可以了
star7th
2021-12-09 10:13:21 +08:00
你注册一个 showdoc 账户, 然后看看其生成的系统文档示例 https://www.showdoc.com.cn/ 。然后根据模板的框架去描述就好。一般情况下都能明白。特殊业务特殊说明。
cairnechen
2021-12-09 10:17:03 +08:00
一个比较好的案例?
https://stripe.com/docs/api
waltcow
2021-12-09 10:18:12 +08:00
github copilot
statement
2021-12-09 10:28:51 +08:00
肯定是找一份文档改
keshawnvan
2021-12-09 11:56:22 +08:00
写文档考验的是精准表达能力,需要多练一练。
ila
2021-12-09 12:02:05 +08:00
swagger
461da73c
2021-12-09 12:14:34 +08:00
文档的好坏不是很好评判,有些人写的文档,看着洋洋洒洒,都是长句,读起来非常费劲。有些人写的短句口语化较多,读起来又不太严肃。
balabalaguguji
2021-12-09 12:49:46 +08:00
用易文档写吧,看看多专业 https://easydoc.net/s/17790664/CZMqMhfW/78558034
reallittoma
2021-12-09 15:30:07 +08:00
Github Copilot 是正确答案
rpman
2021-12-09 15:46:25 +08:00
Copilot YYDS
等着出正式版时打钱了

这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://www.v2ex.com/t/821028

V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX