一、前言

我以前也写过很多文档，也读过很多文档。我能很清晰的分辨出哪些文档更容易让我快速的掌握知识点、哪些文档让我不明白作者到底要表达什么，或者说表达了但只有自己知道真正的前因后果，大部分的细节缺失导致文档的阅读体验就是前后割裂感严重，无法衔接。

我经常在心里吐槽那些写了文档，但是又好像等于没写的文档，每当看到这样的文章时，我总是能在一行小字中找到“工作问题记录、以便以后查阅。”，似乎这些文档的作者写的这些内容，只是为了记录下来，只是为了自己以后会遇到类似的情况时方便处理，而不是为了让别人来阅读的。没办法，我只好又怀着问题重新去找别的文章，也不好说人家写的就不好，人家本来就不是为了让我看的，对吧。

我也不是专业的写手，不过我短浅的阅历以及过往的内容沉淀，让我觉得自己还是可以总结一点东西出来，起码我是产出过几个开源项目，并且文档也是让多数人能够看懂并得以应用的。我举个例子，我自己以前活生生的例子。就是我在做毕业论文的时候，下面坐了好好几排大佬，我一个人在上面吧啦吧啦的讲着，我明显得感觉到每当我在讲完一个我自己在项目中使用的名词时，我都要花大量的篇幅去解释一遍这个名词的意思及其来龙去脉。而我的这些解释又没有写在我的论文内容里面，全凭我自己当时临时发挥。然后最终下面的大佬听完之后或许有人听懂了，但是我依然能看到有人眼里泛着迷茫的眼神。我知道我的得分要被扣了。这个现象其实就是我们没写好文档的一个很糟糕的表现。不仅让我们所处的境界变得尴尬，还让听众或者读者对我的学术深度产生质疑，最重要的是，这样的场景出现多了，严重影响他人对你的信心指数。为了改变这个局面，我们需要将文档写的更加“小白”一些，不是说就不专业了，而是为了照顾“不太专业”的读者。

我是做程序的，一直有一句话在我心中：“用户都是傻子”。因此我做程序时，尽量做得让傻子来用都不会出问题。我写文档的时候也是一样，我在写文档的时候，把三年前的自己作为这篇文章的受众去写，争取写出来的内容以我三年前的知识是能够看懂的，那么这篇文档在我自己这里算是过关了。

二、Ai的回答

来看看chatGPT(3.5)是怎么回答这个问题的：

要写出容易理解和满意的介绍文档和总结报告是一项重要的技能，无论是用于学术论文、业务报告还是其他类型的文档。以下是一些编写介绍文档和总结报告的最佳实践，以帮助您的受众更容易理解和欣赏您的工作：

对受众了解清楚：

• 了解受众：在撰写文档之前，了解您的受众是谁。他们的知识水平、背景和兴趣会影响您的文档内容和语言选择。
• 考虑读者的需求：想想您的受众需要什么信息以及他们对该信息的需求。提供对他们有价值的内容。

介绍文档：

• 清晰的标题和子标题：使用明确的标题和子标题，以帮助读者了解文档的结构和主要内容。
• 提供背景信息：在介绍部分提供背景信息，解释为什么这个主题或问题重要。为什么读者应该关注？
• 概述结构：简要概述文档的结构，告诉读者将在文档中找到什么内容。
• 定义术语：如果文档中使用了专业术语或缩写，确保提供清晰的定义或解释。

总结报告：

• 简明扼要：总结应该是简明扼要的，不要重复文档中的所有细节。突出关键信息。
• 重点突出：强调最重要的发现、建议或结果。让读者知道什么最重要。
• 具体而非抽象：避免使用抽象或泛泛的语言。使用具体的数据和例子来支持您的总结。
• 回答关键问题：确保总结回答了关键问题或提供了解决方案。让读者知道下一步该怎么做。

通用写作建议：

• 清晰的语言：使用简单、清晰、直接的语言。避免使用复杂的句子和术语，除非受众理解它们。
• 段落和标题：使用段落和标题来组织文档。每个段落应探讨一个特定的点。
• 图表和图像：如果适用，使用图表、图像和图表来可视化数据和信息。确保它们易于理解。
• 审校和修订：在发布之前仔细审查和修订文档。检查拼写、语法和逻辑错误。
• 反馈和建议：在完成文档后，请寻求同事或同行的反馈。他们可能提供有价值的建议和观点。
• 保持简洁：不要使用冗长的句子或段落。用最少的词汇传达信息。
• 积极的语气：如果文档中包含批评或问题，提供积极的解决方案或建议。
• 可用性测试：如果可能的话，进行可用性测试，以确保文档容易理解和导航。

最终，写作是一项技能，需要练习。通过不断地反思和改进您的写作，您将变得更善于编写容易理解和满意的文档和报告。

三、我的建议

chatGPT(3.5)的回答多多少少是专业了一点，作为一个读者我觉得它的回答一直在用专业名词告诉我该怎么去写内容，但我首先不理解的就是专业名词，而它似乎又对这些专业名词做了解释，但是解释不是很容易理解。我非常不喜欢用一个词语本身去解释这个词语，我甚至认为这种解释就是完全在敷衍。

但是经过岁月的沉淀，我认为上述回答是正确的，并且也开始理解这些观点，但是它说的太多了，我要说的没有那么多，只有几点：

• 了解受众: 我要写技术java的文档，受众就是所有java开发，但是他们有的人牛逼，有的人还没学习那么深入，那我就以我自己三年前的水平的时候作为我的文档受众去写。

• 考虑读者的需求: 我要写技术java的文档，要写的内容是我想输出的，要看我这篇文章也一定是通过搜索或者推荐进来的，那就是读者希望看的，所以没有限制，我想写什么就写什么。

• 考虑读者的需求2: 我要写一篇总结报告，这份总结报告是别人要求我写的，那么我应该将要求的时间范围内的所有事情都罗列清楚，描写清楚，怎么样才算写清楚，把自己的某位家人作为你这份报告的接收者来考虑。

• 排版格式: 你可能会觉得这并没有什么，只要内容优秀就行了。但是更优秀的，一定是排版很好的。这其实算得上细节上的优化了，任何事情，细节做好了体验就好了。不要标点符号乱用，不要间距不统一，不要颜色使用过多，不要元素使用过多。

• 实际案列、用法: 如果你陈述了一段技巧，但是最后没有该技巧最后达到目的的效果展示，那么你将得不到任何回报。而如果你展示了效果，那么你成为了优秀，但是没把一个活生生的demo贴出来，你就止步于优秀。

四、汇报演讲

当你有一份总结报告，需要在办公室里面，当着其他同事一起进行演讲时，你需要在电脑上打开你的总结文档，然后开始读、汇报、演讲。这个气场有没有，敢不敢于自信的将内容演讲出来需要多锻炼，如果你写的总结内容是很容易让人看懂、听懂的，那么无论你的气场有没有，这场演讲你就已经成功一大半了。

尽量只讲写的内容，就像前言里面说的我之前的故事一样，如果你花了太多的时间去临时解释你写的某个东西时，那么无论你的口才多好，临时解释出来的话，大部分是不会被听众们接受的，而且参会的在座人眼睛是盯着投影上，而你说的东西都不是投影上的东西，他们的专注度也不会转到你说的话里。所以，如果你的总结里尽量就直接把你认为别人可能看不懂的关键词做一个解释，解释就直接写在总结里。你的整个总结如果都满足这个范式的话，你说讲的内容就都是你说写的内容，全程不会出现过多的脱离文档的话语，而参会人全程又都是看着投影的，这会让整个会议的参与度更高。

自信，这部分就属于个人勇气方面的范畴了，没什么好说的，需要多练，需要胆大。你无需在乎自己的发挥时候出色，因为无论多尴尬，等你下一句话之后，大家就会立刻忘记你上一刻的糗态。

五、克服懒惰

人总是懒惰的，谁不希望躺平呀，多舒服。但是如果要产出优秀的东西就必然要付出更多的时间和精力，永远和懒惰是相对的。写了方法你没贴效果，你懒。贴了效果你没贴demo，你懒。文档写好了你没检查，有错别字，还是因为你懒。