Documenting a Project

One-sentence summary

Documentation means writing down your project — in words, diagrams and photos — so that even someone who has never met you can understand it and build it again.

Why it matters

When you finish a project, only you understand it — and only for now. Two months later, even you will have forgotten most of the details: which pin you used, how many ohms the resistor was, why one line of code had to be fixed.

Documentation prevents this forgetting. A good record does three things:

• Others understand it. A friend, a teacher or a competition panel can follow your project without your help.
• You can pick it back up. When you return to the project months later, you know where to start.
• Your learning is shown. In the previous lesson you improved your project; documentation is the record that shows the before and after of that improvement.

Documentation is not a new programming topic. It is a method. It is an engineering skill as important as writing code, and it is usually the step people skip the most.

Throughout this lesson we will follow one example project: an automatic night light. A small circuit that turns an LED on when it is dark and off when it is bright. We built this kind of project in earlier modules; now we are learning to document it.

What parts make up a document?

A good project document is not a pile of random notes. It follows an order — the same path you took while building the project: problem, solution, materials, build, test, result, next step.

The chain from problem to result

Each section answers one question:

• Problem: What were you trying to solve?
• Solution idea: How did you plan to solve it?
• Materials: What did you need?
• Code and diagram: How did you build and program it?
• Test: Did it really work, and how did you check?
• Result: What happened, and how well did it work?
• Next step: What would you change next time?

This chain matches the "evidence of learning" structure exactly. Evidence of learning is a concrete trace that shows you have learned something — and that is precisely what a document is: you do not just say "I made it," you show how you made it and what you learned.

Example 1: Problem and solution for the night light

Here is how the first two sections could read for the night light:

Problem: When I got up for water in the middle of the night, turning on the big light hurt my eyes and woke up my sibling in the room. Solution idea: Build a circuit that automatically turns on a small LED using a light sensor (an LDR) that detects darkness. The LED comes on when the room gets dark and switches off when it gets bright.

Notice the honest, unboastful tone. We do not say "I built a flawless system"; we start from a real need.

Example 2: Writing the materials list as a table

Instead of describing the materials in sentences, putting them in a table is far easier to read. This is called a bill of materials:

Someone can look at this table, gather the same parts and rebuild your project. That is exactly what a good bill of materials is for.

README: The cover page of a project folder

In the software world, every project has a README file. It literally means "read me." It is the short, tidy introduction that the first person who opens the project sees first.

A README is not a long report. It lets someone who does not know the project understand what it is in about a minute.

What goes into a good README?

• The project name and a one-sentence description
• What it does
• Which materials or libraries are needed
• How to set it up and run it
• A photo or a short video link
• The next steps

Night light README draft

# Automatic Night Light

A small LED lamp that turns on automatically in the dark
and switches off in the light.

## What does it do?
It measures room light with an LDR sensor. If the light
drops below a set threshold, the LED turns on.

## What you need
- Arduino Uno
- LDR, LED, 220 ohm and 10K ohm resistors
- Breadboard and jumper wires

## How to run it
1. Build the circuit following the diagram.
2. Upload night_light.ino to the Arduino.
3. Darken the room and watch the LED turn on.

## Test result
The light threshold was set to 400. Covering the sensor
by hand turned the LED on without delay.

## Next step
Make the threshold adjustable with a potentiometer.

This draft is short but complete. Someone can read it, understand the project and build it again.

Showing tests and results in a document

The most valuable part of a project is how you proved it works. A document does not just say "it works"; it records which situation you tried and what you saw. For this you can use a small test scenario table:

The last row matters. Flickering is not a "failure" — it is an observation. Writing it down honestly becomes the starting point for the next improvement (such as adding a small delay for the borderline case). Documentation is not about dressing up success; it is about recording accurately what happened.

Mini practice

To document a small project of your own choosing (a night light, a line-following robot, or a Scratch game), fill in the project folder contents template below:

PROJECT FOLDER TEMPLATE
=======================
1. Project name: _______________________
2. Problem (1-2 sentences): ____________
3. Solution idea: ______________________
4. Bill of materials (table): __________
5. Code / diagram: _____________________
6. Test scenarios (table): _____________
7. Result (what happened): _____________
8. Next step: __________________________
9. Photo / video note: _________________

If you can fill in every line, it means someone else can understand your project too. Any line left blank is probably a part you cannot yet explain to anyone — and that is exactly the part you need to work on most.

Common mistakes

Trying to keep everything in your head

"I'll remember it anyway" is the most common mistake. Details fade within a few days. Keep the document while the project is running, not when it is finished.

Writing down only the working version

Write down your attempts, the failures and the fixes too. Notes like "the LED did not light at first — I had connected the resistor to the wrong leg" make your document real and useful.

Writing materials vaguely

"A resistor" is not enough. Write how many ohms it is. Someone can only rebuild your project with exact values.

Leaving out screenshots and photos

A single photo explains faster than three paragraphs of text. Remember to include a photo of the circuit and of it working.

Safety note

When you add photos or video to a document, protect your personal information:

• Faces and names: Do not put your own or anyone else's face, full name, or school name in the frame. If you are going to share someone's image, get their permission first — and if it is a younger sibling or friend, get their guardian's permission too.
• Home information: Do not photograph your home address, door number or street sign. Watch out for private items visible in the background.
• Sharing: Before posting your document online, show it to an adult. To explain a project, usually just an image of the circuit and the screen is enough; there is no need to show your personal space.

The goal is to share your project proudly, but to do it safely.

Lesson summary

• Documentation means making your project understandable and rebuildable by someone else.
• A good document follows the order problem, solution, materials, code/diagram, test, result and next step — the same order as an evidence-of-learning structure.
• A README is the short introduction file that makes a project understandable in about a minute.
• Writing information such as materials and tests as tables improves readability.
• When adding photos and video, protect personal data such as faces, names and home details, and get permission.

Review questions

1. Write down the three main benefits of documentation.
2. List, in order, the seven main sections of a project document.
3. What is a README file for, and what does its name mean?
4. Why is writing the materials list as a table better than plain sentences?
5. When sharing a photo of a project, which three kinds of personal information should you watch out for?

Answers

1. Others can understand the project, you can continue it months later, and your learning is shown.
2. Problem, solution idea, materials, code/diagram, test, result, next step.
3. A README ("read me") is the short introduction the first person to open a project sees; it quickly explains what the project is and how to set it up and run it.
4. A table shows the parts clearly with their quantities and values, so the reader can easily gather the same parts and rebuild the project.
5. Faces and full names, location information such as home address/door number, and private items in the background; also, get permission if you are sharing someone else.

Source and verification note

For “Documenting a Project”, verification focuses on whether the relationship between What parts make up a document? and Example 1: Problem and solution for the night light remains consistent across examples. A project page should make a result claim only when it is supported by a real prototype, test record or observation. Numbers such as cost, duration and success rate must be labelled clearly when they are estimates.

Next lesson

Preparing a Presentation: Learn to present the project you documented in front of an audience, clearly and briefly.