Lab 1.6: The Scribe

Module: 1.6 - Documentation Generation | ← SlidesDuration: 40 minutes Sample Project: node-express-mongoose-demo

Learning Objectives

By the end of this lab, you will be able to:

• Generate inline documentation (JSDoc/docstrings) with Claude
• Create module-level README files
• Validate generated documentation against actual behavior
• Identify where AI-generated docs might be inaccurate

Prerequisites

• Completed Labs 1.2, 1.3, and 1.5
• Understanding of the project structure and dependencies

Important Warning

Documentation is a Hypothesis

Claude generates documentation by inference, not by running code. Generated docs are hypotheses about what code does. Always validate against tests and runtime behavior.

Setup

# Navigate to the sample project
cd sample-projects/node-express-mongoose-demo

# Start Claude Code
claude

---

Task 1: Find Undocumented Code

Time: 5 minutes

Identify functions or files that need documentation.

Prompts to try:

Show me functions in this codebase that have no comments.

Which files in the app/ directory have the least documentation?

Pick a target: Choose a function or file that:

• Looks important (used in multiple places)
• Has no or minimal comments
• You don't fully understand

Success criteria:

• [ ] Identified at least 2-3 undocumented functions
• [ ] Selected one to document

---

Task 2: Generate Inline Documentation

Time: 15 minutes

Add JSDoc comments to undocumented functions.

Prompts to try:

Add JSDoc comments to the create function in app/controllers/articles.js

Add documentation to all public methods in app/models/article.js

Review the output: Does it explain:

• What the function does?
• What parameters it accepts?
• What it returns?
• Any edge cases or errors?

Validation step:

Show me the tests for this function.

Compare Claude's documentation with what the tests actually verify.

Success criteria:

• [ ] Generated JSDoc for at least 2 functions
• [ ] Validated documentation against tests (if available)
• [ ] Identified any discrepancies

---

Task 3: Generate Module Documentation

Time: 20 minutes

Create a README for a module or directory.

Prompts to try:

Generate a README.md file for the app/models directory. Include:
- Purpose of the module
- Main components and their responsibilities
- Usage examples

Create documentation for the app/controllers module explaining what each controller does.

Validation:

• Do the examples actually work?
• Is the description accurate to what you learned in exploration?

Success criteria:

• [ ] Generated README for at least one module
• [ ] Verified accuracy against your exploration notes
• [ ] Identified any inaccuracies in generated content

---

Validation Checklist

For each piece of generated documentation, verify:

• [ ] Purpose is accurate - Does the description match actual behavior?
• [ ] Parameters are correct - Types and descriptions match the code
• [ ] Return values are accurate - What the function actually returns
• [ ] Edge cases mentioned - Error handling, null checks, etc.
• [ ] Examples work - If Claude provided examples, do they run?

---

Common Failure Modes

Watch for these in generated docs:

Issue	Example	How to Spot
Misleading names	validateEmail only checks for @	Compare with test assertions
Hidden side effects	"Getter" that also modifies state	Read the actual code
Missing edge cases	No mention of null handling	Check error paths in code
Outdated patterns	Docs describe what it "should" do	Run the code to verify

---

Good vs Bad Documentation

Bad (restates the code):

// Sets x to 5
x = 5

Good (explains intent):

// Retry 3 times because the external API is flaky
for (let i = 0; i < 3; i++) { ... }

---

Tips for Success

1. Be specific in requests - "Add JSDoc to public functions" not "document this file"
2. Include examples - Ask Claude to provide usage examples, then test them
3. Document the non-obvious - Skip obvious code, explain complex logic
4. Comment the "why" - Purpose matters more than mechanics

---

Stretch Goals

If you finish early:

1. Generate an OpenAPI spec for an API route
2. Create a Mermaid architecture diagram
3. Document edge cases for error handling

---

Deliverables

At the end of this lab, you should have:

1. JSDoc comments added to at least 2 functions
2. A README.md for at least one module
3. Notes on any inaccuracies you found and corrected
4. Understanding of how to validate AI-generated documentation

---

Next Steps

After completing this lab, move on to Lab 1.7: Full Codebase Reconnaissance - the Day 1 capstone.