这是一个创建于 1003 天前的主题，其中的信息可能已经有所发展或是发生改变。
java 码农一枚，三年多经验，最近新入职一家公司，被说项目文档写的很差，想问大家是如何提升文档编写能力的，有相关的数据或者文章推荐吗
 |
1
maocat 2022-02-06 03:09:44 +08:00 via iPhone
优雅，命名规范的代码就是最好的文档 手动狗头
|
 |
2
Mac 2022-02-06 03:57:59 +08:00 via Android
你是要学行文的风格？那建议学一下写公文。
|
 |
3
israinbow 2022-02-06 05:02:40 +08:00 via Android
接口文档是模板生成，至多自己写几句介绍和注意事项，这些内容只要尽可能简洁明确的表达意图，对于说明性介绍性的文档，面向老板和面向用户的风格也不一样，应用文写作是基础，去学习一下罢。剩下的就是阅读和写作的积累了，简单地说，如果你想让文字强而有力，保持简洁和清晰就足够了。
|
|
4
israinbow 2022-02-06 05:27:20 +08:00 via Android
@israinbow #3 关于简洁 tldr：不完文字游戏，说人话，不要错别字
文档是功能性文章，且目的明确（就是为了告诉读者你要干嘛），所以写作的时候注意不要含有过多的修饰、嵌套否定 /肯定、奇怪的网络用语、暧昧的用词、有歧义的地方打注释消歧义、引用的地方标注来源、文字格式和符号运用也要注意，如用 markdown 编辑的时候给编辑器装个 markdown lint 确保你编辑的时候没有换行或层级问题。最后是文字的排版，这个比较主观，大体上就是你写完之后自己多读两遍，优化不通顺的句子，拆分过长的段落。发布前让周围人试读，他人的评价更客观，询问听取建议后再改一改，当然，也要保持自己的见解，盲目修改就变成他人的 ”主观“ 了。 |
 |
5
msg7086 2022-02-06 07:30:39 +08:00  2
我上学的时候有一门课叫 Technical writing 。
|
 |
6
qaqLjj 2022-02-06 07:37:05 +08:00 via Android
写短句且多换行
|
 |
7
Hyvi 2022-02-06 08:53:01 +08:00
你要问下差在什么地方先。再针对性的改进。
|
 |
9
wangxiaoaer 2022-02-06 10:39:42 +08:00
注意书面化，避免口语化，另外用词要严谨，起码少用黑话。
|
 |
10
ch2 2022-02-06 10:43:20 +08:00 via iPhone
找你觉得好的文档模仿
|
 |
11
byte10 2022-02-06 10:45:55 +08:00 1
文档是很简单的东西，写不好说明思维还在技术层面上。作为过来人，我跟你分享下经验。
关于：听说读写。我就只讲写，写的表达方式有很多种。第一种就是写文档，比如写技术文章等，第二种就是画图表达技术，第三种就是通过动画表达技术。想练习好写文档的能力，首先你多点写技术文档（可以找各种资料然后整合也是可以），然后发给我看，或者发给别人看。如果别人看不懂，说明你写的不好。 第二种画图，比如技术架构图，系统架构图等，你看看别人怎么画的，然后画一个你公司的技术啥的，给大家看，大家能看懂就说明你画的不错。做动画视频也是一样。 如果写文档没有思路，那么就记住一点，如何把大象放进冰箱里，能理解这个思路，相信你写文档就不会再有问题。 关于画图，这个我没有具体可操作的思路教你。 反正别人听不懂，说明你讲的还不行。参考 费曼学习法。 |
 |
12
xuanbg 2022-02-06 10:48:03 +08:00
严格按模版写
|
 |
13
BeautifulSoap 2022-02-06 10:57:11 +08:00 via Android
上上面好多人写文档都没提很重要一点啊：有时候写文档要站在没有接触过你这项目的人的角度来写，如果连领域知识文档都没有后来接手的人看文档等于天书
|
 |
14
balabalaguguji 2022-02-06 11:11:42 +08:00
用一个好的文档工具 https://easydoc.net
|
 |
15
zmxnv123 2022-02-06 11:28:10 +08:00 via iPhone
多写博客试试
|
 |
16
YaakovZiv 2022-02-06 11:51:06 +08:00
我是先写后优化，我应该是团队里被吐槽次数最多的了，别人吐槽以后，我就参考别人的文档样式修改我自己的文档。
文档内容口语化是我当前一大缺陷，已经一年多了，还没改掉。 面对不同人，写不同文档，如果是同行，就省略掉基础解释。如果给客户写，就要当作教零基础学生写文档。 目前我被公司内同事夸奖最多的文档，是两份让人看了就懂，无需多加思考的文档，被很多同级别同事称赞认真去写。 |
 |
17
zjp 2022-02-06 12:13:12 +08:00 6
根据 #4 找到了 google 的课程 https://developers.google.com/tech-writing
还有左耳朵耗子的翻译 https://docs.google.com/document/d/16aoMrMGHPIR1i_eUNRvksdDdwcDG6KiOJN6Vfh-n8-s |
 |
18
konakona 2022-02-06 15:08:13 +08:00
强烈安利楼主看一下《活文档》这本书，通过书可以了解有多少种活灵活现的文档展现形式。
BTW ，我感觉你说你文档写的差，我认为是关键的部分不太行。比如代码展现逻辑、接口顺序、分类归纳、示例健全度等，这些偏向严谨方面的东西做的“很随意”导致的。 |
 |
19
romisanic 2022-02-06 15:09:41 +08:00
不用非得从网上找啥的 你可以问一下这么说你的同事 然后让他把他认为你们内网比较优秀的文档发你看看 模仿着来就行了 写多了就得心应手了
|
 |
20
dingyaguang117 2022-02-06 15:27:58 +08:00
本质还是要考察作者的，归纳整理能力 和 表达能力。
先用思维导图做好提纲（架构），然后再写细节就行。 |
 |
21
Cielsky 2022-02-06 16:10:06 +08:00 via Android
功能性文档的话：简洁无二义。先概括功能，再展开论述。
其他的不清楚 |
 |
22
duke807 2022-02-06 17:08:53 +08:00 via Android
先寫大綱，再寫內容
|
 |
23
leafre 2022-02-06 17:40:20 +08:00
不来个文档示例，很难看出哪里写得差
|
 |
24
kunkunzhang 2022-02-06 17:51:56 +08:00
这样问比较虚，建议拿出一些范例让大家直接帮你纠正是最好的
|
 |
25
liuliancao 2022-02-06 19:54:47 +08:00
提下拙见
1. 了解 markdown 或者 org 等工具，代码着色，分标题，分段落，减少错别字，可以用 docsify 等 2. 代码的 doc tool ，养成写注释的习惯 3. 看看他们的文档，多和同事请教下 |
 |
26
vazo 2022-02-06 21:26:32 +08:00
《科技文档写作实务》
|
 |
27
wangyzj 2022-02-06 22:38:50 +08:00
有时间思考就行
|
 |
28
foam 2022-02-06 23:38:49 +08:00
不知道楼主说的项目文档具体是哪种呢？
API 文档，能够描述清楚请求响应的参数即可；楼主说的可能是 系统设计、业务逻辑文档。 写这类专业性文档，有几点要注意的： 1. 描述清楚上下文。需要用些篇幅来介绍背景、上下文，专业术语。写的时候要代入读者，设身处地思考 TA 能不能看懂。 2. 逻辑清晰。最好列个大纲，不要想到哪写到哪。多用 1 ，2 ，3 描述步骤或者阐述观点。 3. 图文并茂。文字难以描述的，务必带上图。 有兴趣可以看看我的博客。https://foamzou.com 。 若楼主有博客也可以贴出来，我们一起学习交流。 |
 |
29
leonme 2022-02-07 09:31:57 +08:00 via iPhone
金字塔原理
|
 |
30
dahutu 2022-02-07 11:23:24 +08:00
跟着新闻五要素更改一下就能用。
是什么：文档是什么方面的 为什么：文档出现的原因是解决什么的 什么人：那些人需要文档 怎么：文档记录问题是怎么解决的 什么时间：问题什么时候出现的 然后整理一下顺序，应该就可以了 |
 |
31
dany813 2022-02-07 13:20:28 +08:00
学习了，我文档写的也不行
|
 |
32
aguesuka 2022-02-08 00:10:37 +08:00
试着翻译文档, 如果英语不好可以尝试已有翻译的文档, 或者熟悉语言 sdk 的注释文档
|
Select Language