Daily Productive Sharing 838 - What Makes Documentation Good

https://letters.acacess.com/daily-productive-sharing-838/

OpenAI 的技术文档质量相当高，这是为什么呢？Ted Sanders 介绍了他们的一些最佳实践，整篇介绍也是一份质量极高的文档，我们摘录一些最值得借鉴的：

1 写文档要从读者出发 -- 技术文档要让读者快速找到他们想要的信息，所以撰写时就要时刻考虑这一点。 比如要准备目录，要把主题放在每一段的第一句的开头，要让每一段变得精练，多用列表；

2 文档要简单易读 -- 避免使用术语，要用简单句，要考虑语法结构，要避免跨段使用代词。总之要减轻读者的认知负担；

3 要考虑文档的覆盖性 -- 要假设读者对这一话题一无所知，这样的文档技能帮到初学者，也能帮到有经验的人；要写尽量覆盖更多方面的文档，而不是 edge case 的文档。