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.