Day 9: Program Documentation

Learning Objectives

• CRD-2.G: Describe the purpose of a code segment or program by writing documentation.

Essential Questions

• Why is program documentation important?
• What makes documentation effective for different audiences?

Materials Needed

• Presentation slides on documentation types and practices
• Sample code with and without documentation
• Documentation templates
• Code segments for practice

Vocabulary

• Documentation
• Comments
• Inline comments
• Block comments
• API documentation
• User documentation
• Technical documentation

Procedure (50 minutes)

Opening (8 minutes)

1. Review and Connection (3 minutes)

   • Review program design concepts from previous lesson
   • Connect to today's focus on documentation

2. Warm-up Challenge (5 minutes)

   • Show students an undocumented code segment
   • Ask them to determine what it does
   • Discuss the challenges they faced

Main Activities (32 minutes)

3. Lecture: Importance of Program Documentation (10 minutes)

   • Explain why documentation matters:
     • Helps others understand your code
     • Helps future you understand your code
     • Supports collaboration
     • Makes maintenance easier
     • Serves as a communication tool
   • Discuss different types of documentation:
     • Code comments (inline and block)
     • Function/method headers
     • README files
     • User manuals
     • Technical specifications
   • Explain documentation for different audiences:
     • Developers (technical details)
     • Users (how-to instructions)
     • Maintainers (system architecture)

4. Demo: Different Forms of Documentation (7 minutes)

   • Show examples of well-documented code
   • Demonstrate writing effective comments
   • Show examples of external documentation
   • Highlight documentation best practices:
     • Be clear and concise
     • Document why, not just what
     • Keep documentation updated
     • Use consistent formatting

5. Lab: Writing Effective Documentation (15 minutes)

   • Provide students with 3-4 different code segments
   • For each segment, students practice writing:
     • Inline comments explaining complex lines
     • Block comments explaining the overall purpose
     • Function header documentation
   • Students share their documentation with a partner
   • Partners evaluate if they can understand the code based on documentation alone

Closing (10 minutes)

6. Documentation Challenge (7 minutes)

   • Provide students with a more complex code segment
   • Students add comprehensive documentation
   • Documentation must include:
     • Overall purpose
     • Function descriptions
     • Parameter explanations
     • Return value descriptions
     • Key algorithm explanations

7. Preview Next Lesson (3 minutes)

   • Explain that next class will focus on acknowledging code sources
   • Ask students to consider why citing code is important

Assessment

• Formative: Quality of documentation in lab activity
• Documentation Challenge: Completeness and clarity of documentation

Differentiation

For Advanced Students

• Document more complex code segments
• Create multiple types of documentation for the same program
• Write documentation for different audiences

For Struggling Students

• Provide documentation templates with prompts
• Offer simpler code segments
• Give examples of good documentation for reference

Homework/Extension

• Find an open-source project and evaluate its documentation
• Add documentation to a previous programming project
• Create a user manual for a program design from previous lessons

Teacher Notes

• Emphasize that documentation is not an afterthought but an integral part of development
• Point out that the AP exam may ask about documentation purposes and practices
• Connect documentation to collaboration (good documentation enables better teamwork)
• Remind students that documentation will be required in their final project