CS Thinking / core

Documentation

Also known as: docs, code documentation

definition

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. Good documentation makes software maintainable and accessible.

💡 Intuition

Documentation is a letter to your future self (and teammates) explaining what the code does and why you made certain decisions.

Core Idea

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

Formal View

Documentation maps the system's components to human-readable descriptions: for each module M_i with interface I_i, documentation specifies the preconditions, postconditions, and side effects of each operation in I_i.

🔬 Example

Code comments explaining complex logic, a README file describing how to install and run a project, API docs listing available functions and parameters.

🎯 Why It Matters

Good documentation makes software maintainable and accessible. Without it, even the original author can struggle to understand their own code months later. In open-source projects, documentation is often the difference between a tool that gets adopted widely and one that is abandoned.

⚠️ Common Confusion

Don't document what the code does (the code itself says that). Document why it does it — the reasoning and decisions.

💭 Hint When Stuck

When writing documentation, first explain the purpose (why does this code/module exist?). Then describe the interface (what inputs does it take and what does it return?). Finally, include usage examples that show the most common use cases in action.

Related Concepts

Next Steps

code maintenance

How Documentation Connects to Other Ideas

To understand documentation, you should first be comfortable with software development life cycle. Once you have a solid grasp of documentation, you can move on to code maintenance.

Go Deeper

Worked Examples

Step-by-step solved problems

Practice Problems

Test your understanding

Frequently Asked Questions

What is Documentation in CS Thinking?

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. Good documentation makes software understandable, usable, and maintainable by both current and future developers.

Why is Documentation important?

Good documentation makes software maintainable and accessible. Without it, even the original author can struggle to understand their own code months later. In open-source projects, documentation is often the difference between a tool that gets adopted widely and one that is abandoned.

What do students usually get wrong about Documentation?

Don't document what the code does (the code itself says that). Document why it does it — the reasoning and decisions.

What should I learn before Documentation?

Before studying Documentation, you should understand: software development life cycle.