← 2.52.7 →
949 words Slides

2.6 Documentation

Course: Claude Code - Essentials Section: Core Workflows Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

Code tells you how something works. Documentation tells you why and how to use it. Claude Code can generate comprehensive documentation: README files, API docs, code comments, and more. In this video, we'll show how to keep your project documented without the tedious writing.

Key Talking Points

  1. Generating README Files
  2. Ask: "Generate a README for this project"
  3. Claude reads the codebase and creates a complete README with sections: overview, installation, usage, and examples
  4. Saves hours of writing

  5. Show on screen: Ask Claude to write a README and see a well-structured file appear

  6. Writing Code Comments

  7. Comments explain why code exists, not just what it does
  8. Ask: "Add comments explaining the business logic in this function"
  9. Claude adds thoughtful comments that senior developers would write

  10. Show: Comments added to a complex function, highlighting intent

  11. API Documentation (JSDoc, etc.)

  12. Ask: "Add JSDoc to these functions" (for JavaScript)
  13. Claude documents parameters, return types, and examples
  14. Tools like VS Code use this to show inline documentation

  15. Show: JSDoc appears; hover over a function in an editor to show the documentation

  16. Architecture and Design Docs

  17. Ask: "Explain the overall architecture of this project"
  18. Claude generates a document describing how components fit together

  19. Show: A markdown file describing the architecture, data flow, and design decisions

  20. Keeping Docs in Sync with Code

  21. When you refactor (2.2) or change behavior (2.4), documentation can get stale
  22. Ask Claude: "Update the README to reflect the new API"
  23. Claude updates docs to match current code
  24. Show: A change is made; docs are updated to reflect it

Demo Plan

Demo Project: Continue with the same project from 2.1-2.5

Setup: - Project should have some code (from previous videos) - README (if one exists) should be outdated or minimal - Terminal ready with Claude Code session

On-Camera Sequence (2-3 minutes):

  1. Generate a README Generate a comprehensive README for this project
  2. Claude creates a README.md file
  3. Show sections: overview, installation, usage, API, testing

  4. ~40 seconds

  5. Add Code Comments @src/auth.js Add comments explaining the authentication flow

  6. Claude adds comments to a specific file
  7. Highlight comments that explain why, not just what

  8. ~30 seconds

  9. Document Functions with JSDoc (if JavaScript/TypeScript) Add JSDoc comments to the functions in utils.js

  10. Claude adds parameter descriptions, return types, and examples
  11. Show a function with JSDoc in an editor (if time)

  12. ~30 seconds

  13. (Optional) Update Docs After a Change

  14. Make a small code change (e.g., add a parameter to a function)
  15. Ask: "Update the README and JSDoc to reflect this change"
  16. Claude updates the documentation
  17. ~20 seconds

Code Examples & Commands

Asking Claude to document:

Generate a comprehensive README for this project
Add comments explaining the business logic
Document all exported functions with JSDoc
Write architecture documentation
Explain how the API works
Add usage examples to the README
Document the database schema

Documentation requests with scope:

@src/models.js Add comments to explain the data models
@README Add an installation section
@docs/ Create a guide for contributing to this project

Example JSDoc (JavaScript):

/**
 * Calculates the total price of items in a cart.
 * @param {Array<{price: number, quantity: number}>} items - Cart items
 * @returns {number} The total price before tax
 * @example
 * const total = calculateTotal([{price: 10, quantity: 2}]);
 * console.log(total); // 20
 */
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

README Structure Claude Creates:

# Project Name
## Overview
## Installation
## Usage
## API Reference
## Testing
## Contributing
## License

Gotchas & Tips

  1. Comments Should Explain Intent – "Gets the user" is a bad comment. "Fetch user from cache if available, otherwise from DB" is good. Claude usually gets this right.

  2. Keep Docs Close to Code – Documentation in the same repo (not a separate wiki) stays in sync. Encourage this practice.

  3. README Is Your First Impression – New contributors read the README first. A good one saves support questions.

  4. Examples Are Gold – Code examples in documentation are worth a thousand words. Claude includes them; you can ask for more.

  5. Document Edge Cases – Ask Claude: "Document error cases and edge cases" to ensure completeness.

  6. Versioning Matters – If your project has versions or major API changes, mention this in the README.

Lead-out

You now have documented code, and your project is understandable. But what if you need to share a visual explanation? What if there's a screenshot or diagram to include? That's what the next video covers: working with images.

Reference Material

  • Common Workflows - Writing Docs: https://code.claude.com/docs/en/common-workflows
  • Quickstart - Document Code: https://code.claude.com/docs/en/quickstart
  • Best Practices Guide: https://code.claude.com/docs/en/best-practices

Relevant Articles & Posts

  • Documentation Patterns: Joe Njenga's "17 Best Claude Code Workflows" (Medium)
  • Production Practices: Lukasz Fryc's "15 Tips from Running 6 Projects" (DEV Community)
  • Official Resource: Common Workflows - Claude Code Docs (https://code.claude.com/docs/en/common-workflows)

Additional Notes

  • Emphasize: good documentation saves time across the entire team lifetime
  • Show real, well-structured examples (not placeholder text)
  • If time, demo how VS Code shows JSDoc when you hover over a function
  • Note: keeping docs in sync is critical to team productivity
  • Mention CLAUDE.md files (coming in later sections) for documenting your development practices