如何提升编写文档能力

[linksyi18]

java 码农一枚，三年多经验，最近新入职一家公司，被说项目文档写的很差，想问大家是如何提升文档编写能力的，有相关的数据或者文章推荐吗

[maocat]

优雅，命名规范的代码就是最好的文档 手动狗头

[Mac]

你是要学行文的风格？那建议学一下写公文。

[israinbow]

接口文档是模板生成，至多自己写几句介绍和注意事项，这些内容只要尽可能简洁明确的表达意图，对于说明性介绍性的文档，面向老板和面向用户的风格也不一样，应用文写作是基础，去学习一下罢。剩下的就是阅读和写作的积累了，简单地说，如果你想让文字强而有力，保持简洁和清晰就足够了。

[israinbow]

@israinbow #3 关于简洁 tldr：不完文字游戏，说人话，不要错别字

文档是功能性文章，且目的明确（就是为了告诉读者你要干嘛），所以写作的时候注意不要含有过多的修饰、嵌套否定 /肯定、奇怪的网络用语、暧昧的用词、有歧义的地方打注释消歧义、引用的地方标注来源、文字格式和符号运用也要注意，如用 markdown 编辑的时候给编辑器装个 markdown lint 确保你编辑的时候没有换行或层级问题。最后是文字的排版，这个比较主观，大体上就是你写完之后自己多读两遍，优化不通顺的句子，拆分过长的段落。发布前让周围人试读，他人的评价更客观，询问听取建议后再改一改，当然，也要保持自己的见解，盲目修改就变成他人的 ”主观“ 了。

[msg7086]

我上学的时候有一门课叫 Technical writing 。

[qaqLjj]

写短句且多换行

[Hyvi]

你要问下差在什么地方先。再针对性的改进。

[yuezk]

@msg7086 受到启发，可以 Google 一下 Technical writing 然后挑靠前的看看

[wangxiaoaer]

注意书面化，避免口语化，另外用词要严谨，起码少用黑话。

[ch2]

找你觉得好的文档模仿

[byte10]

文档是很简单的东西，写不好说明思维还在技术层面上。作为过来人，我跟你分享下经验。

关于：听说读写。我就只讲写，写的表达方式有很多种。第一种就是写文档，比如写技术文章等，第二种就是画图表达技术，第三种就是通过动画表达技术。想练习好写文档的能力，首先你多点写技术文档（可以找各种资料然后整合也是可以），然后发给我看，或者发给别人看。如果别人看不懂，说明你写的不好。

第二种画图，比如技术架构图，系统架构图等，你看看别人怎么画的，然后画一个你公司的技术啥的，给大家看，大家能看懂就说明你画的不错。做动画视频也是一样。

如果写文档没有思路，那么就记住一点，如何把大象放进冰箱里，能理解这个思路，相信你写文档就不会再有问题。

关于画图，这个我没有具体可操作的思路教你。

反正别人听不懂，说明你讲的还不行。参考 费曼学习法。

[xuanbg]

严格按模版写

[BeautifulSoap]

上上面好多人写文档都没提很重要一点啊：有时候写文档要站在没有接触过你这项目的人的角度来写，如果连领域知识文档都没有后来接手的人看文档等于天书

[balabalaguguji]

用一个好的文档工具 https://easydoc.net

[zmxnv123]

多写博客试试

[YaakovZiv]

我是先写后优化，我应该是团队里被吐槽次数最多的了，别人吐槽以后，我就参考别人的文档样式修改我自己的文档。
文档内容口语化是我当前一大缺陷，已经一年多了，还没改掉。
面对不同人，写不同文档，如果是同行，就省略掉基础解释。如果给客户写，就要当作教零基础学生写文档。
目前我被公司内同事夸奖最多的文档，是两份让人看了就懂，无需多加思考的文档，被很多同级别同事称赞认真去写。

[zjp]

根据 #4 找到了 google 的课程 https://developers.google.com/tech-writing
还有左耳朵耗子的翻译 https://docs.google.com/document/d/16aoMrMGHPIR1i_eUNRvksdDdwcDG6KiOJN6Vfh-n8-s

[konakona]

强烈安利楼主看一下《活文档》这本书，通过书可以了解有多少种活灵活现的文档展现形式。

BTW ，我感觉你说你文档写的差，我认为是关键的部分不太行。比如代码展现逻辑、接口顺序、分类归纳、示例健全度等，这些偏向严谨方面的东西做的“很随意”导致的。

[romisanic]

不用非得从网上找啥的 你可以问一下这么说你的同事 然后让他把他认为你们内网比较优秀的文档发你看看 模仿着来就行了 写多了就得心应手了

[dingyaguang117]

本质还是要考察作者的，归纳整理能力 和 表达能力。

先用思维导图做好提纲（架构），然后再写细节就行。