Definition
Six months after the capstone, a new student wants to continue your air-quality project. Can they find the data, run your code and understand why you chose a threshold of 80? Good documentation is the difference between a project that lives on and one that dies with your laptop.
Project documentation is the set of written materials that explain what a project does, how to use and reproduce it, and why key decisions were made. For an AI project it typically includes a README (overview, setup, how to run, results), a datasheet for the data, a model card, an experiment log, the risk register, a short technical report and comments and docstrings in the code. Good documentation is accurate, up to date, written for its readers and stored with the code under version control.
In simple words
Documentation is a map and a diary for your project. The map shows others how to find their way around and run things; the diary records why you turned left instead of right.
Overview
- Project documentation explains what the project does, how to run it and how it was built.
- Good documentation lets others, and your future self, understand and repeat the work.
- The key parts are a README, code comments, a report and model and data cards.
- Instructions should list exact library versions and steps to reproduce results.
- Write documentation while you work, not only at the end.
- Clear documentation is a major part of how capstone projects are judged.
Why it matters
Documentation lets others trust, reuse, review and build on your work, including examiners, employers and your future self. In professional teams, undocumented work is often treated as unfinished.
Key terms
- README
- The front page of a project: what it is, how to set it up and run it, and where things are.
- Docstring
- A description written inside a function or module explaining what it does, its inputs and outputs.
- Experiment log
- A record of each experiment: date, change, settings, results and conclusion.
- Reproducibility
- The ability for someone else to get the same results by following the documentation.
- Requirements file
- A list of libraries and versions needed, such as requirements.txt.
- Decision record
- A short note on an important decision, the options considered and why one was chosen.
Types
Project documentation comes in several types, each for a different reader.
1. README file
The front page of a project repository.
- How it works: It gives the title, a one-paragraph summary, how to install and run, the folder structure, results and a licence.
- Example: A README.md showing pip install -r requirements.txt and python predict.py to run a demo.
- When to use it: Write it for every project; it is the first thing reviewers and employers read.
2. Code comments and docstrings
Explanations inside the code.
- How it works: Docstrings describe what each function does, its inputs and outputs; comments explain why tricky steps are done.
- Example: A docstring stating that clean_sales(df) removes duplicates and fills missing prices with the median.
- When to use it: Use them for anything not obvious from the code itself.
3. Project report
A full written account of the project.
- How it works: Sections: abstract, introduction, data, methods, results, ethics, limitations, conclusion and references, with figures and tables.
- Example: A 12-page report including a confusion matrix and a table comparing three models.
- When to use it: Use it for submissions, competitions and portfolios. Write it so a reader who missed your presentation can still understand and judge the work.
4. Model cards and data cards
Short structured summaries of the model and dataset.
- How it works: They state intended use, performance by group, limitations, data sources and consent.
- Example: A model card warning that the model was trained only on data from one city.
- When to use it: Include them to show responsible practice. Keep them short, one page each, and update them whenever the model or data changes.
5. Experiment logs and environment files
Records of experiments and of the software setup.
- How it works: A log lists each run's settings and scores; requirements.txt or environment.yml pins library versions; random seeds are fixed.
- Example: A table of 15 runs showing which feature change gave the biggest improvement.
- When to use it: Keep them from the first experiment so results can be reproduced and explained.
Explained in detail
What to include
| Document | Contents for the air-quality project |
|---|---|
| README | Purpose, how to install, how to download data, how to run training and the alert script, main results, contact |
| Datasheet | Sources (CPCB stations, weather data), dates, units, licences, cleaning rules, coverage gaps |
| Model card | Intended use (school alerts), out-of-scope uses (medical decisions), test MAE, recall at threshold 80, errors by area |
| Experiment log | Each model tried, its features and validation scores, and the conclusion |
| Decision records | Why a date-based split; why threshold 80; why a linear model over a random forest |
| Risk register | Risks, mitigations, owners and the go/no-go decision |
Writing a good README
A README is usually the first file anyone opens, so it should answer, within a minute of reading, what the project does, why it matters, how to run it and what it achieved. Start with a one-paragraph summary and a key result. Then give exact setup steps: the Python version, how to create an environment, how to install packages from requirements.txt and where to get the data. Provide the exact commands to clean the data, train the model and produce alerts, and say how long each takes. Add a short results section with the baseline comparison, a section on limitations, a folder map that explains what each directory contains, licence information and how to contact you. Test the README by asking a friend to follow it on a fresh computer; every place they get stuck is a gap to fix.
Documentation habits
Write documentation as you go, not at the end, when details are forgotten. Give functions clear names and short docstrings explaining inputs, outputs and assumptions, such as "PM2.5 in micrograms per cubic metre, daily average". Keep notebooks tidy, with headings that explain each step, and move reusable code into scripts. Record every experiment the day you run it. Pin library versions so results can be reproduced, and fix random seeds. Store all documents in the same repository as the code, so they change together and older versions remain available. Finally, write for different readers: a two-page summary for school principals, the README and model card for technical readers, and the full report for examiners.
How it works
- Create a README at the start and update it as the project evolves.
- Write the datasheet while collecting data and the model card while evaluating.
- Log each experiment and record important decisions with reasons.
- Add docstrings, a requirements file and fixed random seeds.
- Ask someone to reproduce your results from the documentation alone.
Try it yourself
Match the question to the document
Where would a reader find the answer?
- How do I install and run this project?
- Where did the pollution data come from?
- How accurate is the model in each area?
- Why was the threshold set to 80?
- Which models were tried and how did they score?
The project that survived a graduation
Ananya finishes her capstone and leaves for university; a junior, Kabir, takes it over.
Common mistakes
- Writing documentation only at the end, from memory.
- A README that lists features but no setup or run instructions.
- Not pinning library versions, so results cannot be reproduced.
Check yourself
Summary
- Documentation explains what a project does, how to reproduce it and why decisions were made.
- Include a README, datasheet, model card, experiment log, decision records and risk register.
- Write as you go, pin versions, fix seeds and test by asking someone to reproduce the work.
Finished reading?
Sources: Make a README: guidance on writing READMEs · Mitchell et al. (2019), Model Cards for Model Reporting