这是一个创建于 1348 天前的主题，其中的信息可能已经有所发展或是发生改变。
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 MarkLazy 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 本质还是要考察作者的，归纳整理能力 和 表达能力。 先用思维导图做好提纲（架构），然后再写细节就行。 |
 | 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