Documentation and User Guides

Where this helps: making software that other people (and future-you) can actually use and maintain. In the IB Computer Science Internal Assessment this supports the documentation guidelines and the evaluation in Criterion D. Clear documentation is a professional habit worth building.

Table of Contents

  1. Why This Page Exists
  2. The Kinds of Documentation
  3. Writing a User Guide
  4. Code Comments That Earn Their Keep
  5. The README: a Project’s Front Door
  6. Honesty: Citing Your Sources
  7. Quick Check
  8. Match the Document
  9. Practice Exercises
    1. Core
    2. Extension
    3. Challenge
  10. Connections

Why This Page Exists

Code is read far more often than it is written. Six months after you finish a project, you are effectively a stranger to your own code, and anyone else is a stranger from day one. Documentation is how you leave a trail: for the people who use the software, and for the people (including you) who have to change it later.

Good documentation is not about writing more. It is about writing the right things for a specific reader. A user does not want to read your code; a maintainer does not want a marketing brochure. The skill is knowing who you are writing for and giving them exactly what they need.

The Kinds of Documentation

Different readers need different documents. Four kinds cover almost everything.

Kind Who it is for What it answers
User guide The person using the software “How do I do the thing I want to do?”
Technical documentation A developer maintaining the software “How does this work, and how do I set it up and change it?”
Code comments Whoever reads the code next “Why does this particular bit do what it does?”
README Anyone who opens the project “What is this, and how do I get started?”

The most common mistake is mixing them up: putting user instructions in code comments, or dumping technical detail into a guide meant for a non-technical user. Keep the reader in mind and each document writes itself more easily.

Writing a User Guide

A user guide teaches someone to use the software to get their job done. The golden rule is that it is written for the user, not the programmer, so:

  • Task-oriented, not feature-oriented. Organise it around what the user wants to do (“How to record a payment”), not around your menus (“The Payments Screen”).
  • Plain language, no jargon. The user does not know what a “boolean” or a “query” is, and does not need to.
  • Show, do not just tell. Numbered steps and screenshots beat paragraphs. “Click Add, type the amount, press Save” is worth more than a description.
  • Include the awkward moments. A short troubleshooting section (“If the total looks wrong, check…”) saves the user a support message and saves you a headache.

A tiny excerpt of a good user guide reads like this:

Recording a payment

  1. On the main screen, tap Add Payment.
  2. Choose the student’s name from the list.
  3. Type the amount and tap Save. The student’s total updates straight away.

If the student is not in the list, add them first from Manage Students.

Notice there is not one word about how the code works. That is exactly right for this reader.

Code Comments That Earn Their Keep

Comments are documentation inside the code, for the next person to read it. The single most useful rule: comment the WHY, not the WHAT.

The code already says what it does. A comment that repeats it is noise:

Comment Verdict
count = count + 1 // add one to count Useless. The code already says this.
count = count + 1 // skip the header row Useful. It explains why we advance, which the code cannot show.
rate = 0.08 // 2026 sales-tax rate, review each year Useful. It records a decision and a warning a reader could not guess.

Good comments explain the things the code cannot say for itself: the reason behind a choice, a tricky edge case, a value that came from somewhere specific, or a warning about something that looks wrong but is deliberate. If a comment only restates the line beneath it, delete it and let the code speak.

A quick test for a comment: if you deleted it, would the next reader lose information they could not recover from the code itself? If yes, keep it. If no, the comment is clutter, and clutter makes the useful comments harder to spot.

The README: a Project’s Front Door

A README is the first thing anyone sees when they open a project. A good one, kept short, answers a handful of questions fast:

  • What is this? One or two sentences.
  • What does it do? The main features.
  • How do I run it? The steps to get it working, including anything it depends on.
  • How do I use it? A pointer to the user guide, or the basics inline.
  • Who made it, and what can others reuse? Author and licence.

A project with a clear README feels trustworthy and is easy to pick up. A project with no README feels abandoned, even if the code is excellent.

Honesty: Citing Your Sources

Using other people’s work is normal and often sensible. Passing it off as your own is not. If you used a library, followed a tutorial, or adapted a snippet you found online, say so, in a comment next to the code and in your documentation.

This matters for three reasons:

  • Academic honesty. In a school project, presenting borrowed code as your own is a serious integrity breach. A citation protects you.
  • Licensing. Code online comes with licences that set out what you are allowed to do with it. Some require attribution; ignoring that is a real violation, not a technicality.
  • Maintainability. A future reader who knows a chunk came from a specific library or tutorial can go read the original when they need to change it.

Citing a source does not weaken your work. It shows you know where the line is between using a tool and claiming to have built it.

Note for IB CS learners: the Internal Assessment expects you to acknowledge any sources and third-party code you use. Do it as you go, in comments and in your documentation, rather than trying to reconstruct it at the end. Honest attribution is expected, not penalised.

Quick Check

Q1. Who is a user guide written for, and what does it do?

Q2. What should a good code comment usually explain?

Q3. Which comment is worth keeping?

Q4. You adapt a useful code snippet you found online into your project. What is the honest thing to do?

Q5. What makes a user guide effective for non-technical users?

Q6. What belongs in a good README?

Match the Document

For each need, name the kind of documentation that fits: user guide, technical documentation, code comment, or README.

Fill in the blanks.

// A shopkeeper needs to learn how to add a product
// Document: 

// A new developer needs to know how to set the project up and run it
// Document: 

// Explaining, next to a line, why a discount is capped at 50%
// Document: 

// The one-page overview someone sees when they open the project
// Document:

Practice Exercises

Note for IB CS learners: these mirror the documentation and evaluation expectations of the Internal Assessment. Command terms and a suggested mark weight are shown. At least one asks for a full prose response.

Core

  1. Write (4 marks) – Write a short user-guide entry (3 to 5 numbered steps) for a task in an app you know, aimed at someone who has never used it.

  2. Improve (4 marks) – Rewrite these three redundant comments so each explains a why instead: (a) // loop through the list, (b) // set total to 0, (c) // check if x is greater than 10. Invent a plausible reason for each.

  3. Outline (4 marks) – Outline the five things a good README should contain, with one sentence on why each matters.

Extension

  1. Explain (4 marks) – Explain the difference between a user guide and technical documentation, and give one thing that belongs in each but not the other.

  2. Apply (6 marks) – You built a program that uses a free open-source library and one function adapted from a tutorial. Describe exactly how and where you would acknowledge both.

Challenge

  1. Discuss (8 marks) – “Comments make code better, so more comments are always better.” Discuss this claim, referring to the WHY-not-WHAT principle and the cost of clutter. Reach a reasoned conclusion. (Write in prose.)

Connections

© EduCS.me — A resource hub for Computer Science education

This site uses Just the Docs, a documentation theme for Jekyll.