Not sure which lesson to do first? Find your level and get a plan →

CS Thinking · Software Design & Development · Grade 9-12

Documentation

Software documentation is the collection of written descriptions that explain how a system works and how to use it, including inline code comments, user guides, API references, design documents, and README files.


Quick Answer

Software documentation is the collection of written descriptions that explain how a system works and how to use it, including inline code comments, user guides, API references, design documents, and README files. Write each piece for a specific reader: a comment tells the next programmer why a tricky line exists, a README tells a newcomer how to install and run the project, and an API reference tells another developer what a function takes, returns and does when something goes wrong. It has to change whenever the code changes.

Why This Matters

Code shows what a program does but rarely why. Six months later, without a note, nobody knows whether an odd check that skips years divisible by 100 is a bug or the leap-year rule, so they either leave it alone or break it. Good documentation lets a new teammate run a project in minutes instead of days, and lets other programmers call your function correctly without reading its insides.

Intuitive Explanation

Open a function you wrote last term: late_fee(days) returns 0 if days <= 3, otherwise days - 3. It runs, but questions pile up. What does 3 mean? Is the answer in coins, credits, days? A single comment answers them: '# Library rule: 3-day grace period, then 1 credit per extra day.' The code already told you what happens; the comment records why, which is the one thing you cannot recover by reading the code.

Different readers need different documents. Someone using the library app wants a user guide: how to renew a book. A developer calling late_fee wants an API reference: takes a whole number of days, returns credits, gives an error for negative days. A newcomer to the project wants a README: install with one command, run with another, find the tests here. Handing a reader the wrong document helps about as much as handing them none.

Not every comment helps. '# subtract 3 from days' above days - 3 just restates the code, and it quietly becomes false if the grace period changes to 5. Worse is stale documentation: a README that still says 'run setup.py' after the project switched tools sends every newcomer straight into an error. Useful documentation passes two checks: it says something the code itself does not, and it is still true.

Think of it like this. Documentation is the label on a medicine bottle: what it is for, how much to take, what not to mix it with. The pills work without the label, but nobody can use them safely. And like a label, it is only useful while it matches what is inside; a wrong label is more dangerous than a blank one.

Core idea. Code tells the computer what to do. Documentation tells humans why the code exists and how to use it.


When to Use

Think about documentation when a task involves explaining code to someone else, a project being handed over or reopened months later, a function that other people will call, or a teammate who cannot get the project running. Decide who the reader is, then choose a comment, README, API reference or user guide. If the code gives the wrong result, that calls for debugging; if working code must change to meet new needs, that is code maintenance, and the documentation is updated with it.

Tip. Ask: Is the task to explain existing code to a human reader, in a comment, README or guide, without changing what it does?

How to Recognize It

Ask who will read the text, when they will read it, and whether the software it describes already exists.

  1. Is the text written for a person, so the program would behave exactly the same if it were deleted?

    Yes means documentation, such as comments or a README. If deleting it changes what runs, it is code; if it sets out what is still to be built, it is a Design Specification.

  2. Does the text explain why a line of code exists rather than repeat what it does?

    Yes means it is a useful comment. A comment like 'add 1 to x' only restates the code, so the reader learns nothing new.

  3. Is the reader someone using the software rather than changing it?

    Yes means user documentation, such as a help page or a guide. A reader who will change the code needs developer documentation: comments, an API reference, design notes.

  4. Is the text a step-by-step plan for how an algorithm will work, written before coding?

    Yes means it is Pseudocode, a planning tool; it may later be kept alongside the code, but its first job is to guide the coding.

Documentation vs Design Specification vs Pseudocode vs Interface

All four describe software in words, and parts of each can end up in the same project folder. Ask whether the text explains a system that exists, sets out what is still to be built, plans an algorithm's steps, or is the contract that code itself must follow.

Documentation

Meaning
Documentation is writing that explains existing software to people, from code comments to user guides.
Key test
Describes software that exists; deleting it changes nothing the program does.
Example
A comment saying the request is retried three times because the school Wi-Fi often drops the first one.

Design Specification

Meaning
A design specification states what software must do before it is built, so it can be checked later.
Key test
Written before the code, about the behavior that is required.
Example
'The app must show the next three buses for any stop' is a requirement, not documentation.

Pseudocode

Meaning
Pseudocode is a plain-language plan of an algorithm's steps, written to guide the coding.
Key test
A plan of steps, not an explanation of finished code.
Example
FOR EACH stop IN route, SHOW the stop name AND its arrival time.

Interface

Meaning
An interface is the set of inputs, outputs and rules that code must follow when it uses a module.
Key test
The contract itself; an API reference is the documentation describing it.
Example
next_buses(stop_id, count) returning a list is the interface; the page explaining it is documentation.

Formula & Notation

How to read it: Common documentation formats include inline comments (// or #), docstrings (triple quotes in Python), JSDoc tags (@param, @returns), and Markdown files (README.md).

Worked Examples

Example 1 — Document a function for its callers

Easy

A function average(scores) returns None when the list is empty and otherwise returns sum(scores) / len(scores). Write documentation so a teammate can use it without reading the body, and include what average([70, 85, 90]) and average([]) give.
Show the steps and the answer
  1. State the purpose in one line: 'Return the mean of a list of test scores.'

    A caller first needs to know what the function is for, in their own terms, not how it loops.

  2. Describe the input and output: 'scores: a list of numbers. Returns the mean as a decimal.'

    The input and output are what callers depend on; naming the types stops someone passing in a string of digits.

  3. Describe the unusual case: 'Returns None if scores is empty, instead of dividing by zero.'

    Callers have to handle None, and they cannot know to unless it is written down; this is the line most often missing.

  4. Add an example: average([70, 85, 90]) gives about 81.67, because 245 / 3 = 81.666...; average([]) gives None.

    A worked example lets a reader check their understanding in seconds.

Answer: 'Return the mean of a list of test scores. scores: a list of numbers. Returns the mean as a decimal, or None if the list is empty. Example: average([70, 85, 90]) is about 81.67; average([]) is None.'

Takeaway: Function documentation covers purpose, inputs, output and the unusual cases, plus one example a reader can check.

Example 2 — Wrong code, not wrong docs

Standard

A README says: 'Run the game with python main.py; scores save to scores.txt.' A new team member runs it and scores.txt stays empty. She finds that last week someone deleted the line that writes the score, by accident; nothing else changed. Should the team fix the README or the code?
Show the steps and the answer
  1. Compare the README with what the team wants: scores should still be saved to scores.txt.

    Documentation describes intended behaviour, and here the README matches the intent; the code drifted away from it.

  2. Classify the problem: the program behaves wrongly, so it is a bug.

    Editing the README to say 'scores are not saved' would make the docs agree with broken code and hide the defect.

  3. Restore the deleted line, play one game, and open scores.txt: it now contains the score.

    That test shows the README is true again without changing a word of it.

Answer: Fix the code, not the README. The documentation was right; the deleted save line is a bug.

Takeaway: When docs and code disagree, decide which one states what the system should do; update the docs only when the behaviour changed on purpose.

Example 3 — Find the mistake: an echo and a stale comment

Application

Raj's game code has '# add 1 to tries' above 'tries = tries + 1', and '# player gets 3 tries' above 'if tries > 5: end_game()'. Find the mistakes in the comments and correct them.
Show the steps and the answer
  1. Read the first comment against its line: it repeats exactly what tries = tries + 1 already says.

    It adds no information; a reader still does not learn why tries is being counted.

  2. Read the second comment against its line: the game ends when tries > 5, so a player gets 5 tries, and the 6th ends the game.

    The comment says 3, so it is stale: the limit was changed and the comment was left behind. Anyone trusting it would test the wrong number.

  3. Rewrite: replace the first with '# count this guess toward the limit' or delete it, and change the second to '# players get 5 guesses; the 6th ends the game'.

    Comments should give purpose and rules, and a comment beside a number must be edited in the same change as that number.

Answer: Comment 1 only echoes the code (state its purpose or delete it). Comment 2 is out of date: the code allows 5 tries. Corrected: '# players get 5 guesses; the 6th ends the game'.

Takeaway: A comment should say something the code does not, and it must change in the same edit as the code it describes.

Where You'll See It

  • A board game's rule sheet

    The printed rules that come with a board game are documentation: they tell a new player how to start, what each piece does, and what to do in tricky situations, without explaining how the game was manufactured.

  • Coming back to your own Scratch project months later

    If you open a game you coded last semester and left comments like 'this loop makes the sprite bounce off the wall,' you can pick it back up fast; with no comments you have to re-figure-out your own logic from scratch.

  • A README on a shared class project

    When two students share code on GitHub, a README that says how to run the program and what each file does lets a teammate contribute without messaging back and forth for an hour.

Common Mistakes

  1. The slip: Good comments restate what each line of code does, like '// add 1 to x' above x = x + 1.

    Why it's tempting: It feels thorough and 'well-commented,' and it's easy to write because you just translate the code into English.

    Instead: The code already says WHAT it does; useful documentation explains WHY (the reason, the edge case handled, the decision made). Comment the intent, not the syntax.

  2. The slip: Once you write documentation, the job is done and you never touch it again.

    Why it's tempting: Writing docs feels like a one-time chore you can check off, and updating them isn't as satisfying as shipping new features.

    Instead: Docs must be updated whenever the code changes. Stale documentation that describes old behavior is worse than none, because it actively misleads readers.

  3. The slip: Documentation means only the formal manual or API reference.

    Why it's tempting: Those are the most visible, official-looking forms of documentation.

    Instead: Documentation is the whole family: inline comments, READMEs, design notes, user guides, and commit messages all count and all serve different readers.


Mini Practice

Try these on your own. Tap Reveal when you want to check.

  1. Improve this comment: i = i + 1 # add 1 to i. The line is there to skip the header row of a spreadsheet.

    Hint: Explain why the line is there, not what it does.

  2. Write a docstring for def average(nums): return sum(nums) / len(nums). Include its purpose, input, output and one error case.

    Hint: What happens if nums is empty?

  3. Which of these comments explain why rather than what? (a) # loop over students (b) # skip absent students so the class average is not lowered (c) # set x to 0 (d) # retry 3 times because the school Wi-Fi drops connections

    Hint: A why comment gives a reason the code itself cannot show.

  4. A README says 'Run python app.py --port 8000', but the code now reads the port from a PORT environment variable, and --port gives an error. What should be done, and what does the stale line cost?

    Hint: Who follows the README, and what happens when they do?

  5. A teammate cannot work out how to call your parse_date function, which returns correct results. Does it need documentation or debugging?

    Hint: Is the code wrong, or is it just unclear how to use it?

  6. The documentation for divide(a, b) says only: 'Returns a divided by b.' What important case is missing?

    Hint: Which input makes division impossible?

Want the full set?

50 practice questions for this concept — free to try, every one with a complete worked solution showing the why, not just the answer.

Frequently Asked Questions

What is a docstring?

A docstring is a string placed as the first line inside a Python function, class or module, in triple quotes, describing what it does, its parameters and what it returns. Unlike a # comment, Python keeps it attached to the function, so help(average) prints it, and many editors show it when you hover over a call. Tools can also gather every docstring in a project into web pages of API documentation automatically.

How much should I comment my code?

Less than beginners expect, and in different places. Good names do much of the work: total_price needs no comment, while tp does. Save comments for what the code cannot say for itself: why a strange-looking choice was made, a limit the code depends on, or a known problem. A useful check is to ask what a classmate reading the code for the first time would get wrong, and comment exactly that.

Who writes documentation in a real company?

Developers write the comments, docstrings and READMEs for code they build, because they know why it works the way it does. Larger companies also employ technical writers, who turn that knowledge into user guides, tutorials and API pages for readers outside the team. Many open-source projects treat documentation as part of every change: a new feature is not accepted until its documentation has been written too.

What should a README contain?

A good README answers a newcomer's first questions in order: what the project does, how to install it, how to run it, and a short example of using it. Larger projects add how to run the tests, how to report a bug and whom to contact. It sits in the top folder of the project, usually written in Markdown, so sites like GitHub display it on the project's front page.

Learning Path

Documentation

You are here

You should know the Software Development Life Cycle, because documentation comes out of every phase: the spec in requirements, design notes in design, comments while coding, user guides at deployment. This concept adds how to match a document to its reader and keep it true. Next, Code Maintenance depends on it: changing code safely years later starts with understanding why it was written that way.

See Also