Computer Science › Section H · Software engineering › Topic H.7

Documentation

Software is of little use if people cannot learn to use it, and of little lasting value if nobody can safely change it. Documentation is the written knowledge that makes both possible, and good teams treat it as part of the product, not an afterthought.

Why documentation matters

A finished program is only part of a software product. Users need to learn what it does and how to use it. Maintainers, often years later and often not the original authors, need to understand how it works and why it was built that way. Administrators need to install, configure and update it. Each group needs different information, written in different language, so documentation is planned for its readers. Because most of a system's life is spent in maintenance, as "The software life cycle" showed, clear documentation is one of the cheapest ways to lower the cost of every later change.

Three kinds of documentation

Software documentation is usually divided by purpose into three kinds. User documentation explains the software's features and how to use them; it is written for users, in the terms of the application rather than of programming. System documentation describes the software's internal composition so that it can be maintained: the source code itself, the design documents and the requirements. Technical documentation explains how to install and service the software: setting it up, adjusting its settings, applying updates and reporting problems. Think of a lift in an office block: riders need the signs by the buttons, engineers redesigning it need the drawings, and the service technician needs the maintenance manual.

User documentation

User documentation once meant a printed manual. Today it is mostly online or built into the software: getting-started guides, searchable help pages, step-by-step tutorials, short videos, tooltips that appear when the pointer rests on a button, and answers to frequently asked questions. Release notes tell users what has changed in each version. Good user documentation is organised around tasks users want to do, such as "Export a report as PDF", rather than around the program's menus or modules. Because clear help makes software easier to adopt, many companies employ technical writers to produce it, and they treat it as part of the product's appeal to customers.

System documentation and the code

The most important system documentation is the source code, so it must be readable. That means a clear high-level language, a modular design, and meaningful names: days_late says what total_d does not. Most organisations adopt a style guide covering layout, indentation and naming; Python's community standard is PEP 8, which uses names such as late_fee for functions and LateFee for classes. Comments should explain why, not repeat what: "# multiply by 0.25" adds nothing, while "# Library policy: fines are capped at $5" records a reason no one could guess from the code. System documentation also keeps the requirements specification and design documents, with the reasons behind major decisions, so maintainers do not undo choices that were deliberate.

Worked example: documenting a function

A maintainer finds def f(d): return min(max(d, 0) * .25, 5.0). 1. Rename it so the code explains itself: def late_fee(days_late):. 2. Add a docstring, a string placed first in the function body that describes it. Its first line states the purpose: "Return the late fee in dollars for an item returned days_late days late." 3. Its next lines state the rules and edge cases: 0.25 per day, capped at 5.00; zero or negative days cost nothing. 4. Add examples in the docstring in the form >>> late_fee(3) followed by the expected result 0.75, and likewise late_fee(40) giving 5.0 and late_fee(-2) giving 0.0. 5. Check: tracing the code gives 0.75, then min(10.0, 5.0) = 5.0, then 0 × 0.25 = 0.0, so all three examples are right. Had the cap been written 5, late_fee(40) would print 5, not 5.0, and that example would fail.

Documentation that tools can use

Docstrings are not just comments: the program can read them. In Python, help(late_fee) prints the docstring, and late_fee.__doc__ holds it as a string. The examples written in the worked example can be run automatically: python -m doctest fees.py runs every >>> example in the file and prints nothing when they all pass, so documentation that falls out of step with the code is caught as a failing test. Similar tools generate a browsable reference from structured comments, such as Javadoc for Java and Sphinx for Python. This API documentation, short for application programming interface, tells other programmers how to call each function or class without reading its code.

Technical documentation

Technical documentation is written for the people who install and run software rather than those who use or modify it: system administrators, operations staff, IT support. It covers system requirements, installation steps, configuration settings and what each one does, how to apply updates and back up data, which log files to check, and how to report problems to the developers. On a personal laptop the user and the administrator are the same person, so the line between user and technical documentation blurs. In a school or company network, one administrator may look after software for thousands of users, and there the distinction is sharp.

Worked example: sorting documents by kind

A school timetabling product ships with five documents. Classify each. 1. "How to swap two lessons by dragging them": written for teachers using the program, so user documentation. 2. A diagram of the modules and the database tables, with notes on why each table was split: for maintainers, so system documentation. 3. "Installing on the school server, and setting the term dates": for the IT administrator, so technical documentation. 4. Comments and docstrings inside the source code: system documentation. 5. Release notes saying "Room clashes are now highlighted in red": aimed at users, so user documentation. Check: each was classified by its reader and purpose, not by its format.

Keeping documentation current

Out-of-date documentation can be worse than none, because readers trust it. Documentation should therefore be written during development, as each part is designed and built, not left until the end, when memories have faded and deadlines press. Many teams treat documentation like code. They keep it in the same version control repository, update it in the same change that alters the behaviour, and check it in code review. A README file at the top of a project explains what it is and how to start, and a changelog lists what changed in each version. Automated checks such as doctest catch examples that no longer match.

Common mistakes to avoid

First, comments that repeat the code instead of giving reasons. Second, cryptic names that force readers to decode the program. Third, writing user documentation in programmers' terms, or around menus instead of tasks. Fourth, mixing up the three kinds: installation steps are technical documentation, and design documents are system documentation. Fifth, changing the code but not the documentation, so readers are misled.

Key takeaways

Documentation serves three audiences. User documentation explains features and how to use them, mostly online and organised by task. System documentation, chiefly readable source code plus design and requirements documents with their reasons, supports maintenance. Technical documentation explains installing, configuring and servicing the software for administrators. Good names, style guides such as PEP 8 and comments that explain why make code self-documenting; docstrings can be read by help() and tested with doctest. Documentation must be written alongside the code and kept current.

Flashcards

Flashcard

User documentation

Explains a program's features and how to use them

For users, in the application's terms.

Test your understanding

Question 1 of 5

A page explains how to install a hospital booking system on a server and set its backup schedule. Which kind of documentation is it?

Question 2 of 5

Which comment is the most useful?

Question 3 of 5

A docstring contains >>> late_fee(8) followed by 2.0. Using the reading's late_fee, what happens when python -m doctest runs it?

Question 4 of 5

Why should documentation be written during development rather than at the end?

Question 5 of 5

A maintainer wants to know why the database splits customer addresses into a separate table. Where should the answer be?

← Previous topicNext topic →