Program Documentation: Internal and External

Master the essential skill of documenting programs for CSEC IT exams and real-world programming

📚 Intended Learning Outcomes

By the end of this article, you should be able to:

  1. Explain the purpose of program documentation
  2. Differentiate clearly between internal and external documentation
  3. Identify documentation examples in exam scenarios
  4. Explain the role of documentation in program development and maintenance
  5. Respond accurately to CSEC exam questions on documentation
1

Why Program Documentation Matters

📝 Documentation = Communication

Program documentation is the written information that explains what a program does, how it works, and how to use it. It's essential for:

🔄

Maintenance

Helps programmers understand and modify code months or years later

👥

Teamwork

Enables multiple programmers to work on the same project

🎓

Training

Helps new programmers or users learn the system

💡 CSEC Exam Insight

Documentation questions frequently appear in Paper 1 (multiple choice) and Paper 2 (structured questions). You might be asked to:

  • Define documentation types
  • Identify examples from descriptions
  • Explain why documentation is important
  • Suggest appropriate documentation for scenarios
2

Definition of Program Documentation

📋 Official CSEC Definition

Program documentation is written information about a computer program that describes its purpose, operation, and maintenance requirements.

Key point: Documentation is about the program, not the program itself.

Documentation vs. Program Code

Program Code
PRINT "Enter age: "
INPUT age
IF age >= 18 THEN
PRINT "Adult"
ELSE
PRINT "Minor"
END IF

The actual instructions the computer follows

Documentation
# This program determines if a person is an adult or minor
# based on the legal age of 18 years.
User Manual:
1. Run the program
2. Enter your age when prompted
3. Program displays "Adult" or "Minor"

Information about what the program does and how to use it

3

Internal Documentation

🔍 CSEC Definition

Internal documentation is documentation that exists within the program code itself, intended for programmers who will read, modify, or maintain the code.

Key Characteristics

  • Audience: Programmers and developers
  • Location: Inside the program files
  • Purpose: Help understand, debug, and modify code
  • Timing: Created during and after programming

🎯 Exam Tip

When asked about internal documentation in exams, always mention that it's "within the program code" and for "programmers". These keywords often earn marks.

4

Examples of Internal Documentation

1. Program Comments

Explanatory notes ignored by the computer but read by programmers:

# ============================================
# Function: calculate_discount
# Purpose: Apply 10% discount to orders over $500
# Parameters: order_total (float)
# Returns: final_total (float)
# ============================================
FUNCTION calculate_discount(order_total)
IF order_total > 500 THEN
discount = order_total * 0.10
final_total = order_total - discount
ELSE
final_total = order_total
END IF
RETURN final_total
END FUNCTION

2. Meaningful Identifiers

Poor Example
a = 5000
b = a * 0.15
c = a + b

Problem: What do a, b, c represent? No one can tell!

Good Example
subtotal = 5000
vat_amount = subtotal * 0.15
total_price = subtotal + vat_amount

Benefit: Variable names explain their purpose

3. Indentation and Layout

Proper formatting makes program structure clear:

# Well-indented code shows structure clearly
FOR student = 1 TO class_size
INPUT exam_score
IF exam_score >= 75 THEN
grade = "A"
ELSE IF exam_score >= 60 THEN
grade = "B"
ELSE IF exam_score >= 50 THEN
grade = "C"
ELSE
grade = "F"
END IF
PRINT "Student ", student, " grade: ", grade
NEXT student
5

External Documentation

📄 CSEC Definition

External documentation is documentation that exists separately from the program code, intended for various stakeholders including users, managers, and clients.

Key Characteristics

  • Audience: Users, managers, clients, future programmers
  • Location: Separate documents/files
  • Purpose: Help use, evaluate, or understand the program
  • Timing: Created before, during, and after development

⚠️ Common Exam Mistake

Students often confuse "external" with "for people outside the company." Actually, external documentation can be for anyone (including programmers) but exists outside the code files.

6

Examples of External Documentation

1. User Manuals

📖 Caribbean Context Example

A user manual for a Caribbean hotel booking system might include:

  • How to check room availability during Carnival season
  • How to process payments in EC$, TT$, or USD
  • How to apply local taxes (10-15% VAT)
  • How to print receipts and invoices

2. Program Specifications

Detailed description created before programming begins:

PROGRAM: Caribbean Restaurant POS System
PURPOSE: Process food orders and calculate bills
INPUTS: - Food items (jerk chicken, roti, etc.)
- Quantities
- Customer details
PROCESSING: - Calculate subtotal
- Apply 12.5% VAT
- Apply service charge if party > 6
OUTPUTS: - Itemized bill
- Total amount due
- Receipt

3. System Flowcharts

🎨 Visual Documentation

Flowcharts are excellent external documentation because they visually represent program logic. In CSEC exams, you might be asked to interpret or create flowcharts as part of documentation questions.

4. Technical Documentation

  • Installation guides: How to set up the software
  • System requirements: Hardware/software needed
  • Troubleshooting guides: Solutions to common problems
  • API documentation: For programmers using the software
7

Internal vs External Documentation

Aspect Internal Documentation External Documentation
Definition Documentation within the program code Documentation separate from program code
Main Audience Programmers, developers Users, managers, clients, future programmers
Primary Purpose Help understand, debug, modify code Help use, evaluate, understand program
Location Inside program files Separate documents/files
Examples Comments, meaningful variable names, indentation User manuals, specifications, flowcharts, technical guides
Created When During and after programming Before, during, and after development
CSEC Focus Code readability, debugging questions SBA requirements, user documentation questions
🔍 Quick Identification Activity

Identify each as Internal (I) or External (E) documentation:

  1. A printed guide showing how to use accounting software
  2. Comments in Python code explaining a complex calculation
  3. A flowchart showing program logic
  4. Variable names like "customer_age" instead of "x"
  5. A technical manual for system administrators
  6. Proper indentation showing IF-ELSE structure
8

Documentation Across the Program Development Cycle

Documentation is not a one-time task! It happens throughout development:

1

Analysis

External: Requirements specification

2

Design

External: Algorithms, flowcharts

3

Implementation

Internal: Comments, good variable names

4

Testing

External: Test plans, results

5

Evaluation

External: User manuals, final docs

6

Maintenance

Both: Update all documentation

📝 CSEC SBA Requirement

For your School-Based Assessment, you must provide comprehensive documentation including:

  • Problem statement (external)
  • Algorithm/flowchart (external)
  • Program code with comments (internal)
  • Test plan and results (external)
  • User guide (external)
  • Evaluation (external)
9

Real-World and Exam Scenarios

Scenario 1: Caribbean Bank System

A bank in Trinidad develops new software for processing loans. What documentation would they need?

💻

Internal (for programmers)

  • Comments explaining interest calculations
  • Clear variable names like "loan_amount"
  • Proper indentation in code
👥

External (for various users)

  • User manual for bank tellers
  • Technical guide for IT staff
  • System specifications document
  • Flowchart of loan approval process

Scenario 2: School Grading System

A CSEC student creates a program to calculate grades. What documentation should they include in their SBA?

⚠️ Common Student Errors in Exams

  1. Mixing up definitions: Saying internal documentation is "for internal staff" instead of "within the code"
  2. Vague examples: Saying "manual" without specifying "user manual" or "technical manual"
  3. Missing keywords: Not using terms like "within the program code" or "separate documents"
  4. Incomplete lists: Only giving one example when asked for "examples" (plural)
10

CSEC Examination Focus

How Documentation Appears in Exams

A

Multiple Choice Questions

  • Identifying documentation types
  • Selecting correct definitions
  • Choosing appropriate examples
B

Short-Answer Questions

  • Defining terms
  • Giving examples
  • Explaining importance
C

Structured Questions

  • Comparing internal vs external
  • Documenting algorithms
  • Creating test plans

🎯 Exam Answer Strategy

When answering documentation questions:

  1. Be specific: "User manual" not just "manual"
  2. Use key terms: "within the program code" for internal
  3. Give multiple examples: If asked for examples, give 2-3
  4. Explain why: Always explain importance, not just list
  5. Relate to scenario: Tailor answers to given context
11

CSEC-Style Practice Questions

📝 Practice Questions

Answer these exam-style questions. Click "Show Answer" to check your responses.

Question 1

Define the term "internal documentation" as used in program development.

Show Answer
Model Answer:
Internal documentation is documentation that exists within the program code itself, intended for programmers who will read, modify, or maintain the code. It includes comments, meaningful variable names, and proper indentation.
Question 2

State TWO examples of external documentation.

Show Answer
Model Answer:
1. User manual - instructions for end-users on how to operate the program
2. Program specifications - detailed description of what the program should do, created before programming begins

Other acceptable answers: System flowchart, technical manual, test plan, algorithm documentation.
Question 3

Explain why documentation is important in program development.

Show Answer
Model Answer:
Documentation is important because:

1. It helps programmers understand, debug, and modify code later, especially if they didn't write it originally.
2. It enables users to learn how to operate the program correctly without constant assistance.
3. It supports teamwork by allowing multiple programmers to work on the same project.
4. It aids in maintenance and future upgrades of the program.
Question 4

Identify whether each item below is internal or external documentation:

  1. Comments within a Python program
  2. A printed guide for using accounting software
  3. Meaningful variable names like "student_age"
  4. A system flowchart
Show Answer
Model Answer:
a) Internal documentation (within the program code)
b) External documentation (separate document for users)
c) Internal documentation (within the program code)
d) External documentation (separate visual representation)
Question 5

A Caribbean supermarket is developing a new inventory system. What type of documentation would help the store manager understand how to use the system?

Show Answer
Model Answer:
The store manager would need external documentation, specifically a user manual that provides step-by-step instructions on how to:

1. Add new products to the inventory
2. Update stock levels after sales
3. Generate inventory reports
4. Process orders and deliveries

The manual should use simple language and include Caribbean-specific examples (local products, currencies).
Question 6

Improve the internal documentation in this pseudocode:

INPUT a, b
c = a * b
PRINT c
Show Answer
Model Answer:
# Calculate area of a rectangle
INPUT length, width
# Area = length × width
area = length * width
PRINT "Area: ", area

Improvements made:
  • Added comment explaining program purpose
  • Used meaningful variable names (length, width, area)
  • Added comment explaining the formula
  • Improved output message
Question 7

When in the program development cycle should documentation be created?

Show Answer
Model Answer:
Documentation should be created throughout the entire program development cycle:

1. Analysis phase: External documentation (requirements)
2. Design phase: External documentation (algorithms, flowcharts)
3. Implementation phase: Internal documentation (comments during coding)
4. Testing phase: External documentation (test plans, results)
5. Evaluation phase: External documentation (user manuals)
6. Maintenance phase: Update all documentation when changes are made
Question 8

Differentiate between internal and external documentation.

Show Answer
Model Answer:
Aspect Internal Documentation External Documentation
Location Within the program code Separate from program code
Audience Programmers Users, managers, clients
Purpose Help understand and modify code Help use and evaluate program
Examples Comments, variable names Manuals, specifications
✓

Key Summary for CSEC Success

Internal Documentation

  • Definition: Within program code
  • For: Programmers
  • Examples: Comments, good variable names
  • Exam focus: Code readability

External Documentation

  • Definition: Separate documents
  • For: Users, managers
  • Examples: Manuals, specifications
  • Exam focus: SBA requirements

🎯 Final Exam Tips

  1. Memorize clear definitions for "internal" and "external"
  2. Always give specific examples in answers
  3. Use key terms: "within the code", "separate documents"
  4. Explain why documentation matters
  5. Practice with past paper questions
Scroll to Top