Good code comments
Explain why a decision exists, what assumptions the code makes and what could surprise the next reader.
Writing & documentation overview
↑Documentation is useful when someone can return to it months later and still understand the decisions behind the code. That person might be a teammate, a reviewer or your future self.
Start with the question
Section titled “Start with the question”Before writing, ask what the reader needs to accomplish. A page called “How to handle collisions in Unity” is easier to navigate than a page called “Things I learned today”. Put the answer near the top, then show the reasoning and limitations.
Helpful technical guides
Describe prerequisites, show a small working example and tell the reader how to verify the result.
Use a consistent structure
Section titled “Use a consistent structure”- Quick overview. State what this page helps with in one or two sentences.
- Detailed explanation. Show the mechanism and why it matters, using a concrete example.
- Code and examples. Use labelled source languages and explain what readers should expect to see.
- Common mistakes. Describe failure modes and edge cases with practical guidance.
- Verification. Tell the reader how to check that the result is correct.
- Further reading. Link to reliable primary documentation and related topics.
Choose the right amount of detail
Section titled “Choose the right amount of detail”A short overview helps readers decide whether they need the page. The in-depth section helps when they do. Neither should be missing. Include working examples with assumptions, not just syntax without context.
Explore writing code comments or structuring documentation for specific patterns.