Daily Productive Sharing 838 - What Makes Documentation Good
One helpful tip per day:)
OpenAI's technical documentation is of exceptionally high quality. Why is that? Ted Sanders shared some of their best practices, and the entire piece itself is a testament to high-quality documentation. Here are some noteworthy takeaways:
- Write from the reader's perspective - Technical documentation should allow readers to quickly find the information they're seeking. It's crucial to bear this in mind while writing. For instance, it's helpful to have a table of contents, position the main topic at the beginning of every paragraph, keep paragraphs concise, and make extensive use of lists.
- Keep it simple and clear - Documentation should be easy to read. Avoid jargon, opt for simple sentences, consider grammatical structure, and refrain from using pronouns across different paragraphs. The aim is to minimize cognitive load for the reader.
- Consider the breadth of your documentation - Assume that your reader might be completely new to the topic. Such a comprehensive approach will benefit both novices and experienced individuals. Aim to write documentation that covers a broader spectrum rather than focusing solely on edge cases.
If you enjoy today's sharing, why not subscribe
Need a superb CV, please try our CV Consultation
已经有超过五千位朋友通过各种渠道订阅我们的内容，你还在犹豫什么呢？不如直接支持我们 :)
OpenAI 的技术文档质量相当高，这是为什么呢？Ted Sanders 介绍了他们的一些最佳实践，整篇介绍也是一份质量极高的文档，我们摘录一些最值得借鉴的：
- 写文档要从读者出发 -- 技术文档要让读者快速找到他们想要的信息，所以撰写时就要时刻考虑这一点。 比如要准备目录，要把主题放在每一段的第一句的开头，要让每一段变得精练，多用列表；
- 文档要简单易读 -- 避免使用术语，要用简单句，要考虑语法结构，要避免跨段使用代词。总之要减轻读者的认知负担；
- 要考虑文档的覆盖性 -- 要假设读者对这一话题一无所知，这样的文档技能帮到初学者，也能帮到有经验的人；要写尽量覆盖更多方面的文档，而不是 edge case 的文档。
需要更丝滑的移民体验，不妨试试 AwesomeVisa