Skip to main content

Writing Good Docs

Documentation is all about putting useful information in other people’s heads. Here are some practical tips to make your documentation better.

Make It Easy to Scan​

Most readers won’t read everything from top to bottom. They jump around, looking for what solves their problem. Help them find answers quickly.

  • Use Clear Section Titles. Titles should act as signposts. They help readers decide whether to read on or move to another section.

  • Be Specific with Titles. Instead of vague titles like “Results,” use something informative, like “Streaming Reduced Time to First Token by 50%.” This gives readers immediate insight.

  • Include a Table of Contents. A table of contents helps readers find information faster, just like a map helps travelers navigate. It also gives a snapshot of what’s in the document.

  • Keep Paragraphs Short. Short paragraphs are easier to skim. If you have a key point, consider making it its own one-sentence paragraph.

  • Start with Clear Topic Sentences. Open paragraphs with a sentence that summarizes what’s coming next. This way, readers don’t need to rely on prior text to understand.

  • Put Main Points First. Lead with the most important information. Don’t build up to your main point—state it upfront.

  • Use Bulleted Lists and Tables. These formats make information easier to digest. Use them whenever you can.

  • Highlight Key Information. Don’t hesitate to bold key points to help readers find essential information.

Write Clearly and Effectively​

Poorly written text makes reading harder. Make it easier on your readers.

  • Keep Sentences Simple. Break long sentences into shorter ones. Cut out unnecessary words and use direct language.

  • Be Clear and Specific. Avoid sentences that can be misinterpreted. Instead of saying, “Title sections with sentences,” say, “Write section titles as sentences.” Clarity matters.

  • Avoid Confusing Structures. Don’t make readers hold onto information until the end of a sentence. Start with the main idea. For example, instead of “You need flour, eggs, and milk to make pancakes,” say, “To make pancakes, you need flour, eggs, and milk.”

  • Limit Demonstrative Pronouns. Instead of saying, “This is important,” specify what “this” refers to. Clarity helps comprehension.

  • Be Consistent. Use the same style throughout. If you start with Title Case, stick with it. Consistency helps readers focus on content rather than style.

  • Avoid Assuming Readers’ Thoughts. Don’t say things like, “Now you probably want to know…” Instead, directly state, “To call a function, you need to…”

Be Helpful for Everyone​

Readers come with different levels of knowledge and understanding. Aim to help everyone, not just experts.

  • Write Simply. Use simple explanations. Not everyone speaks English as a first language, and some might struggle with complex terminology.

  • Avoid Abbreviations. Write out terms fully. It’s easier for beginners and doesn’t cost much for experts.

  • Provide Solutions for Common Issues. Even if most readers know how to do something, include basic explanations for those who don’t. It can prevent frustration and help beginners.

  • Use Accurate Terminology. Avoid jargon. Use terms that are clear to newcomers. Instead of “context limit,” say “max token limit.”

  • Keep Code Examples Simple. Make sure examples are self-contained and don’t require extra dependencies. This helps readers focus on the main idea.

  • Prioritize Common Topics. Focus on frequently encountered issues. For example, how to count tokens is more valuable than rare problems.

  • Don’t Model Bad Habits. Always demonstrate best practices. If API keys shouldn’t be stored in code, never show an example that does.

  • Start with a Broad Introduction. Ground your topic with some context. This can help readers feel more secure before diving into the details.