A program that works is good – but a program that works and is easy for others to understand is much better. Documentation is the written explanation that goes with a program. In this post you will learn the two types: internal and external documentation.

Build on what you learned in Forms 1–3

These Lower School ICT posts cover the basics of this topic:

• Introduction to Scratch Programming – building programs others can follow
• How to share a Scratch Project – sharing a project with notes for others

In this post:

• Why document a program?
• Internal documentation
• External documentation
• A well-documented program in Python and C

Why document a program?

• Other programmers (or you, months later!) can understand and maintain the program.
• Users can learn how to install and use the program.
• Errors are easier to find and fix.

Internal documentation

Internal documentation is written inside the source code. It includes:

• Comments – notes that the translator ignores. In Python they start with #; in C they go between /* and */ (or after //).
• A header comment at the top: program name, author, date and purpose.
• Meaningful variable names such as rate_per_km instead of r.
• Indentation and white space so the structure (IFs and loops) is easy to see.

External documentation

External documentation is separate from the code. It includes:

• User documentation (user manual or help files) – tells users how to install, start and use the program, with screenshots and troubleshooting tips.
• Technical documentation – for programmers: the algorithms, flowcharts, IPO charts, data types used and test results.

A well-documented program

# ------------------------------------------------------------
# Program:  Taxi fare calculator
# Author:   A. Student
# Date:     16 October 2026
# Purpose:  Works out a taxi fare from the distance travelled.
#           Fare = base fee + (rate per km x distance)
# ------------------------------------------------------------

BASE_FEE = 5.00       # fixed charge for every trip ($)
RATE_PER_KM = 2.50    # charge for each kilometre ($)

# Input: distance in kilometres
distance = float(input("Enter distance travelled (km): "))

# Process: calculate the fare
fare = BASE_FEE + RATE_PER_KM * distance

# Output: display the fare to 2 decimal places
print("Fare: $" + format(fare, ".2f"))

/* ------------------------------------------------------------
   Program:  Taxi fare calculator
   Author:   A. Student
   Date:     16 October 2026
   Purpose:  Works out a taxi fare from the distance travelled.
             Fare = base fee + (rate per km x distance)
   ------------------------------------------------------------ */
#include <stdio.h>

#define BASE_FEE 5.00      /* fixed charge for every trip ($) */
#define RATE_PER_KM 2.50   /* charge for each kilometre ($)   */

int main(void)
{
    float distance, fare;

    /* Input: distance in kilometres */
    printf("Enter distance travelled (km): ");
    scanf("%f", &distance);

    /* Process: calculate the fare */
    fare = BASE_FEE + RATE_PER_KM * distance;

    /* Output: display the fare to 2 decimal places */
    printf("Fare: $%.2f\n", fare);
    return 0;
}

Sample run with 12 km: Fare: $35.00. Notice the header comment, the comments for input, processing and output, the named constants and the meaningful variable names.

Video: Software Engineering: Crash Course Computer Science #16 – https://www.youtube.com/watch?v=O753uuutqH8

Paper 1 practice (multiple choice)

Choose the best answer for each question. Try them all before you check.

1. Comments written inside the source code are an example of
(A) external documentation
(B) internal documentation
(C) a user manual
(D) test data

2. Which is an example of external documentation?
(A) Indentation
(B) A user manual
(C) Meaningful variable names
(D) A comment

3. In Python, a comment begins with
(A) //
(B) /*
(C) #
(D) REM

4. ONE purpose of program documentation is to
(A) make the program run faster
(B) help others understand and maintain the program
(C) remove syntax errors automatically
(D) translate the program

5. Which variable name is the MOST meaningful?
(A) x
(B) tp
(C) total_price
(D) a1

Paper 2 practice (structured question)

A programmer has written a program to calculate the monthly salaries of workers at a factory in San Fernando. The program will be used by the payroll clerk and updated by other programmers in the future.

(a) Distinguish between internal and external documentation. (2 marks)

(b) Give TWO examples of internal documentation the programmer should include. (2 marks)

(c) State TWO items that should be included in the user manual for the payroll clerk. (2 marks)

(d) Explain why documentation is important for the programmers who will update the program in the future. (2 marks)

Total: 8 marks

Next: CSEC Information Technology Notes (course page)

Syllabus link: This post is relevant to the CSEC® Information Technology Syllabus (CXC 30/G/SYLL 17), Section 8: Program Implementation, Specific Objective 6 (“effectively document programs”).

Attributions to media used in this post:

No third-party images are used in this post. Embedded videos are credited on YouTube to their channels.

© 2026 Vedesh Kungebeharry. All rights reserved.