辛宝Otto

辛宝Otto 的玄酒清谈

北漂前端程序员儿 / 探索新事物 / Web Worker 主播之一/内向话痨
xiaoyuzhou
email

从一个文档 PR 学习如何让 Readme 编写得更好

image

背景#

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

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

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

逐一做个解释。

文档是用来帮助人的#

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

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

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

image

溯源 来源

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

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

文档的 PR#

点击查看 PR

image

我的想法:

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

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

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

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

加载中...
此文章数据所有权由区块链加密技术和智能合约保障仅归创作者所有。