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