背景#

最近在思考这个问题，如何让技术文档做的更好？

最近有两件事情促使我开始思考：

• 看到了 ViteConf 上 Sarah Rainsberger 分享的《Stop writing docs; Start helping》视频
• 最近 sync-to-xlog 插件的一个文档 PR

逐一做个解释。

文档是用来帮助人的#

Sarah Rainsberger 是 Astro 的文档主管，这是她在 ViteConf2023 上的演讲。我做了视频搬运，可以在 B 站观看 # Astro 文档负责人分享什么是好的技术文档，如何改进

内部链接： [[stop writing docs start helping]]

举了一个非常经典的例子：

溯源 来源

上图内容是，介绍安装的方案。这个例子有点击中人心，原来的技术文档非常好，能激励读者、解释作者的想法。改进后只需要一句话，几个单词。

在此时此刻，读者需要的帮助是告诉他如何进行安装，清晰、明确地告诉读者就好了。

文档的 PR#

请点击查看 PR

我的想法：

• 勇敢使用 H1
• 如何安装，要区分前置。该截图改加注释，标红加箭头，不犯法
• 减少口水话，更中立、忠实、平静地描述事实
• 还得多看多写

文档可以从无到有，从有到优。

后面编写文档时刻留意，争取做得更好。

我看提到的那个文档大一统理论挺好，或许可以翻译。