Skip to content
CS Capstone Handbook

Documentation

Read this when someone other than you needs to run or understand your system; it gives you which documents to write and how much detail each needs.

Documentation is the infrastructure of knowledge transfer. It is what lets someone else (a new team member, your project partner, a future maintainer, or your future self) understand and use your work without having to ask you. Without it:

  • Onboarding new contributors takes days instead of hours.
  • Project partners cannot evaluate or use the system you built.
  • Work that is not documented effectively ceases to exist after you graduate.
  • Code review becomes harder because reviewers lack context.

The goal of documentation is not to document everything. It is to document the right things at the right level of detail, kept close to the work it describes.

The most useful idea for deciding what “the right things” means is Diataxis, Daniele Procida’s framework, which observes that documentation serves four distinct needs and that most bad documentation is two of them mashed together. A tutorial takes a beginner through a first success and is learning-oriented. A how-to guide helps someone who already knows the system accomplish a specific task. Reference describes what exists, precisely and without narrative. Explanation covers why things are the way they are. The reason this matters practically is that the needs conflict: a tutorial that pauses to explain every design decision loses the beginner, and a reference that tells a story is useless to someone scanning for a function signature. When a page feels wrong and you cannot say why, it is usually serving two of these at once.

This handbook is itself an instance of the framework: guides are explanation, activities are how-to, and assignment rubrics are reference.

The reader who tests your documentation hardest is the one who inherits the project after you leave: someone who cannot ask you anything and has to get the system running from what is written down. Write for that person and the rest takes care of itself.

Repository Documentation

Section titled “Repository Documentation”

Every project repository should contain a standard set of documents. These files live in the root of the repository and are rendered automatically by GitHub, GitLab, and most hosting platforms.

README

Section titled “README”

The README is the front page of your project. Anyone encountering your repository for the first time will read it first. A good README answers:

  • What is this? One paragraph describing the project and its purpose.
  • Who is it for? Who uses it, and what problem does it solve?
  • How do I run it? Step-by-step setup and run instructions, starting from a clean machine.
  • How do I use it? Basic usage examples with expected outputs.
  • What is the status? Is this a prototype? Production software? Actively maintained?
  • How do I contribute? Link to CONTRIBUTING.md.
  • What is the license? Link to LICENSE.

The test: can a new team member get the project running locally in under 30 minutes using only the README? If not, update it.

CONTRIBUTING.md

Section titled “CONTRIBUTING.md”

Explains how to contribute to the project. This is the technical expression of your working agreement. It should include:

  • Development setup (dependencies, environment variables, local services needed).
  • Branching strategy (e.g., feature branches off main, naming convention).
  • PR requirements (required reviewers, review checklist, CI must pass).
  • Coding standards (linter, formatter, style guide).
  • Definition of Done.
  • How to write and run tests.
Team Working AgreementThe working agreement informs the contents of CONTRIBUTING.md.

LICENSE

Section titled “LICENSE”

Every project should have a license, even if it is the team’s own product. Without a license, default copyright rules apply, meaning no one else can legally use or build on your work.

If your project is open-source, choose a license. If it is closed-source (proprietary or under NDA), include a copyright notice. If you are contributing to an existing FOSS project, inherit its license.

Common choices:

  • MIT: permissive, minimal restrictions. A good default for open-source projects.
  • Apache 2.0: permissive, with explicit patent grants. Preferred by many companies.
  • GPL v3: copyleft, meaning derivatives must also be open-source. Good for projects that want to stay open.

choosealicense.com is the best resource for making this decision.

CHANGELOG

Section titled “CHANGELOG”

A changelog documents what changed between versions of the software. It is especially important for:

  • Projects used by your project partner, who needs to know what to test after each release.
  • FOSS contributions, where maintainers and users follow releases closely.

Format: Keep a Changelog is the most widely used convention. Use semantic versioning for release tags.

Code Documentation

Section titled “Code Documentation”

Code documentation lives alongside the code itself. Its purpose is to explain intent and context that the code alone cannot convey.

Comments: When and How

Section titled “Comments: When and How”

The most common documentation mistake is under-commenting complex logic and over-commenting obvious code.

Good comment:

# Binary search over the sorted segment list.
# Segments are stored as (start, end) tuples; we match by start offset.

Unnecessary comment:

i = 0  # initialize i to zero

The rule: comment the why, not the what. The code already says what it does. The comment explains why it is done this way, what assumption it relies on, or what subtle behavior to watch for.

Docstrings and API Documentation

Section titled “Docstrings and API Documentation”

Public functions, classes, and modules should have docstrings. At minimum, a docstring should describe:

  • What the function does (not how).
  • Parameters and their types.
  • Return value.
  • Exceptions that may be raised.

Tools like JSDoc (JavaScript), Sphinx (Python), TypeDoc (TypeScript), and Rustdoc (Rust) can generate navigable API documentation from well-written docstrings.

For REST APIs, OpenAPI (Swagger) is the industry standard. Defining your API in an OpenAPI spec gives you documentation, client code generation, and request validation for free.

User Documentation

Section titled “User Documentation”

User documentation explains how to use the software, not how it was built. It is written for end users, not engineers. For a Capstone project, this might be:

  • A user guide or wiki explaining how to complete key workflows.
  • In-app help text or tooltips.
  • A short video walkthrough.

User documentation is especially important for consultancy projects where the project partner will hand the software to non-technical users after the year ends.

Developer Documentation

Section titled “Developer Documentation”

Developer documentation targets people who will build on, maintain, or deploy the system. It includes:

  • Architecture overview: a description of major components and how they fit together. Link to your design document.
  • Data model: the schema and what each entity represents.
  • Environment setup: how to configure development, test, and production environments.
  • Deployment guide: how to deploy the system, including environment variables and infrastructure requirements.
  • Troubleshooting guide: common failure modes and their resolutions.
Technical DesignThe design document is the primary source of architectural documentation.

Versioning

Section titled “Versioning”

Use semantic versioning (MAJOR.MINOR.PATCH) for releases:

  • MAJOR: breaking changes (old integrations may stop working).
  • MINOR: new features, backwards-compatible.
  • PATCH: bug fixes.

Tag releases in your repository (git tag v1.0.0). This makes it easy to identify which version your project partner is running and to roll back if a release introduces a regression.

Documentation Tools

Section titled “Documentation Tools”

Nothing in this table is required, and a project documented entirely in Markdown files in the repository is a perfectly good outcome. Reach for a tool when the manual version has started to drift: generated API documentation cannot fall out of step with the code the way a hand-written list can, and a documentation site earns its keep once you have more pages than a reader can navigate by filename.

Need Tool
Project documentation site Docusaurus, MkDocs
API documentation (REST) Swagger UI / OpenAPI, Redoc
Python API docs Sphinx, pdoc
JavaScript / TypeScript TypeDoc, JSDoc
Diagrams as code Mermaid, PlantUML
Changelog Keep a Changelog convention

Best Practices

Section titled “Best Practices”
  • Write documentation when you build the feature, not at the end of the term.
  • Keep documentation close to the code. Documentation that lives far from what it describes becomes stale quickly.
  • Treat README setup instructions as a test: run them on a fresh machine or in a clean environment.
  • Delete documentation that is wrong. Outdated docs are worse than no docs: they actively mislead.
  • Use diagrams. A system diagram in the README is worth three paragraphs of prose.
  • Review documentation in code review. Do not merge PRs that introduce undocumented public APIs.

Some Truths About Documentation

Section titled “Some Truths About Documentation”

Documentation rots, and it rots faster than code because nothing fails when it is wrong. A broken function breaks a test; a README describing a setup procedure that changed four months ago passes every check in your repository and costs the next person an afternoon. This asymmetry is the whole problem, and it is why the only documentation that reliably stays current is documentation something else depends on: a README whose commands you actually run, a generated API reference, a changelog your release process reads.

That gives a sharper rule than “keep it updated”, which no team has ever managed by willpower. Prefer documentation that is executed or generated over documentation that is merely written. If your setup instructions are a script someone runs, they cannot silently drift. If they are prose, they will. Where prose is unavoidable, put it in the repository next to what it describes and change it in the same pull request, because a document in a separate wiki is one nobody will remember to open.

Stale documentation being worse than none is stated often enough to have become a slogan, so it is worth saying what the actual cost is. Missing documentation makes the reader ask someone, which is slow but ends with a correct answer. Wrong documentation makes them confident, and they discover the error somewhere downstream, usually after building on it. This is why deleting a section you know is obsolete is a legitimate act of maintenance, not a failure to do the real work.

The honest thing about writing it: almost nobody enjoys it, and the advice to document as you build is correct and also very hard to follow when a deadline is close. What works better than resolve is making the moment specific. Attach it to something you already do, such as the pull request that adds a feature or the review that looks over your docs/ directory, so the question is never “should I write documentation today” but “does this change alter anything a reader was told”.

Finally, this is a career skill rather than a chore, and the claim is more concrete than it sounds. Almost every senior engineering role is partly a writing job: design documents, incident reports, proposals, review comments that change someone’s mind. The people who advance are disproportionately the ones who can make a technical argument in prose, and a capstone project is one of the few low-stakes places left to practice on something real.

Documentation in Industry and Academia

Section titled “Documentation in Industry and Academia”

At Google, documentation is treated as a first-class engineering deliverable. The Software Engineering at Google book dedicates an entire chapter to it. Engineers who write clear internal design documents, maintainable READMEs, and useful code comments are recognized as making the whole organization more effective.

In open-source projects, documentation quality is often the difference between a project that gets adopted and one that gets ignored, regardless of the underlying code quality.

In academic research, documentation ensures reproducibility: another researcher should be able to run your code and reproduce your results using only your documentation. This standard is a useful benchmark for Capstone projects as well.

Additional Readings

Section titled “Additional Readings”

Diataxis is the single most useful thing on this list: it takes about twenty minutes and it will change how you structure every document you write afterwards. The style guides are worth skimming once and then keeping open while you write.

Sources and further reading

Activities that exercise this