Internal versus external program documentation

Name:

Date:

Class:

Quick Questions

Shade in the A or B circle for each question.

1. A comment written above a function in the .py file is which type of documentation?

A Internal documentation

B External documentation

2. A separate user guide explaining how to run a program is which type of documentation?

A External documentation

B Internal documentation

3. Who is user documentation mainly written for?

A People who use the program

B Programmers who maintain the code

4. Which document is written for the programmers who must maintain the program?

A User documentation

B Technical documentation

5. Which of these is an example of internal documentation?

A A PDF user manual

B A docstring inside a function

Match the Pairs

Draw a line connecting each item on the left to its match on the right.

Left column		Right column
1# Convert marks to a percentage		ATechnical documentation is written for developers and maintainers. End users need the user documentation instead.
2User guide: Click Save to store your marks		BModule: grades.py \| Input: marks list \| Output: average
3Internal documentation describes a function's purpose, inputs and output from inside the code		C"""Return the average of a list of marks."""
4Technical documentation is external and lists each module's purpose, inputs and outputs for maintainers		DA user guide is external documentation, not internal. It is a separate document and is not written inside the code.
5A user guide is internal documentation because it explains how the program works		EInternal documentation: a comment written inside the code to explain what it does
6Technical documentation is for end users who have never seen the code		FExternal documentation: a separate document that tells users how to operate the program

Definitions

internal vs external documentation

Fill in the Blanks

Complete each line of code by filling in the missing parts.

_ Internal documentation: stays in the code

___ area(w, h): """Return the area of a rectangle.""" return w * h

def area(w, h): """Return the area of a rectangle.""" print(area._______)

def internal(doc): return doc __ ("comment", "docstring")

docs = ["user guide", "technical document"] ___ d in docs: print(d)

Spot the Error

Shade in the letter of the line that contains an error.

Question 1

A def area(w, h):

B """Return the area."""

C return 2 * (w + h)

Question 2

A def total(prices):

B """Add up all prices.""

C return sum(prices)

Question 3

A # Module: grades.py

B # Purpose: average of marks

C // Input: list of marks

D # Output: the mean as a float

Question 4

A def show_help():

B """Show user help."""

C print("Enter a mark 0-100")

D print("Type q to quit"

Question 5

A def circle_area(r):

B # Inputs: r, the radius

C Output: area as a float

D return 3.14159 * r ** 2

Answer Key

Internal versus external program documentation

Section A: Quick Questions

A — Internal documentation

A — External documentation

A — People who use the program

B — Technical documentation

B — A docstring inside a function

Section B: Match the Pairs

# Convert marks to a percentage → Internal documentation: a comment written inside the code to explain what it does

User guide: Click Save to store your marks → External documentation: a separate document that tells users how to operate the program

Internal documentation describes a function's purpose, inputs and output from inside the code → """Return the average of a list of marks."""

Technical documentation is external and lists each module's purpose, inputs and outputs for maintainers → Module: grades.py | Input: marks list | Output: average

A user guide is internal documentation because it explains how the program works → A user guide is external documentation, not internal. It is a separate document and is not written inside the code.

Technical documentation is for end users who have never seen the code → Technical documentation is written for developers and maintainers. End users need the user documentation instead.

Section C: Definitions

internal vs external documentation — Internal documentation is inside the code (comments, docstrings). External is separate, like a user guide or technical document covering each module's purpose, inputs and outputs.

Section D: Fill in the Blanks

# Internal documentation: stays in the code

def area(w, h):
    """Return the area of a rectangle."""
    return w * h

def area(w, h):
    """Return the area of a rectangle."""
print(area.__doc__)

def internal(doc):
    return doc in ("comment", "docstring")

docs = ["user guide", "technical document"]
for d in docs:
    print(d)

Section E: Spot the Error

C — The docstring says the function returns the area, but this line calculates the perimeter. Internal documentation must match what the code does. It should be return w * h.

B — The docstring is closed with only two quotation marks, so Python sees an unfinished string and gives a syntax error. A docstring must end with three quotation marks.

C — Python comments start with #, not //. This header comment documents the module's inputs and would cause a syntax error. It should be # Input: list of marks.

D — The closing bracket is missing, so the function that prints the user help text will not run. It should be print("Type q to quit").

C — The # is missing, so Python tries to run the documentation as code and gives a syntax error. Comments that record outputs must start with #.