Your quiz script runs on your laptop, but a classmate can't start it. Or your science model works, yet your teacher can't tell which readings you measured and which you expected. The build may be finished, but the explanation isn't there yet. I'd start the record while the project is still on the desk, rather than trying to remember every step on the final night.
Documentation gives someone a route through the work: what you built, how to run or repeat it, what you tested and what still needs fixing. Keep it practical. A short setup guide and an honest test log can explain more than several pages of polished claims.
1. Define the question and draw the system
Write down the question and the limits of the project. “Make a quiz program” leaves a lot undecided. “Ask five multiple-choice questions, reject invalid choices and report a score out of five” gives you something to test. For science work, name what you'll change, what you'll measure and which conditions you'll keep comparable.
- List materials, software versions and dependencies you actually use.
- Draw the main components and label what moves between them.
- Record the source of borrowed designs, data and code.
- Name what the project does not attempt to establish.
Draw the main parts next. A sensor model might show a reading going to a controller and then an output. Software might show input, validation, calculation and display. Use labelled sample files when sharing; passwords, access tokens and other people's personal details don't belong in the public record.
2. Write setup steps while the work is fresh
My advice is to write setup instructions for someone who hasn't watched you build the project. Name the files, where they go, what command to run or preparation to make, and what should happen next. “Install everything and run it” won't help a classmate work out whether a missing dependency or your code caused the error.
- State prerequisites before the first instruction.
- Give exact filenames and relevant settings.
- Show one sample input and its expected output.
- Ask another person to follow the written steps without verbal hints.
Watch where your test reader pauses and fix that part of the guide. One working laptop doesn't tell you about every other setup, so name the environment you've checked. For experiments, follow your school's approved safety procedures and include the preparation your teacher requires.
3. Keep observations, fixes and conclusions separate
Keep a test record with the version, starting conditions, input, expected result, actual result and next action. Write down raw measurements and units before calculating averages. With code, try normal answers, boundary values and invalid input. Don't skip the awkward cases.
- Give each test a short identifier and a date.
- Change one cause at a time where practical.
- Retest the failing case and a previously working case after a fix.
- Keep unexpected observations instead of deleting inconvenient rows.
Finish by explaining what the results support and what you'd improve next. Make your own contribution to group work clear. A planned feature belongs under future work; a simulated reading needs to be labelled as a simulation. That makes the record much easier to question and check.
| Deliverable | Target reader | Must-have sections | Data table required? | Biggest mistake to avoid |
|---|---|---|---|---|
| GitHub README.md | A person trying to run coding work | Purpose, requirements, setup, usage, tests, limits | Include test cases; measurements when relevant | Missing commands or exposing credentials |
| Lab notebook / science report | Teacher, supervisor or experiment reviewer | Question, method, units, observations, analysis, limits | Usually: record raw measurements with units | Replacing observations with a polished conclusion |
| Two-page viva / judge summary | A busy examiner or fair judge | Goal, system sketch, strongest result, contribution, limitations | Include a compact key-results table when useful | A poster-like claim with no traceable evidence |
| Project poster with QR link | Class visitors or a science-fair audience | Question, labelled diagram, key result, credit and link to full record | Show the key measurements; link the full log | Tiny text or claims that the report cannot support |
Worked Example
Here's a small Python quiz example: five questions, with choices A through D. The first answer is B. Version 0 compares the raw input with “B,” prints Correct or Incorrect, and moves on even if the entry isn't a valid choice. Each test starts again at question one with score zero, so one result won't affect the next.
Before testing, set the rules: accept lowercase letters and extra spaces, but ask again for a blank or invalid choice without changing the score or question number. I'd write those rules beside the test cases. Otherwise, it's easy to change your idea of “correct behaviour” after seeing what the program happens to do.
| Test input | Expected output | Actual version-0 output | Correction and retest |
|---|---|---|---|
| " b " | Accept B; score 1; question 2 | Incorrect; score 0; question 2 | Trim spaces and uppercase; retest produces score 1 |
| "x" | Invalid choice; score 0; stay on question 1 | Incorrect; score 0; question 2 | Validate A–D before scoring or advancing |
| Empty string | Ask for an answer; score 0; stay on question 1 | Incorrect; score 0; question 2 | Handle blank input; retry without changing state |
Start with the spaces and capitalisation. Trimming “ b ” and converting it to uppercase gives B, which now earns one point. But that doesn't solve everything: “x” becomes X and still isn't an allowed answer. Check that the input is A, B, C or D before scoring it or moving to the next question.
For blank input, show “Enter A, B, C or D” and stay on the same question. Rerun all three cases, then try B as an ordinary correct answer and A as a valid wrong answer. B should add a point and advance; A should advance without adding a point. Those checks catch a fix that accidentally blocks every answer.
The final summary can now show the three original failures, the changed validation order and the retest results. These sample outcomes follow from the version-0 rules above, so someone else can repeat the exercise. Keep the failures in the record; they explain why the changes were needed.
I'd use GitHub's README guidance as a starting checklist, then adapt the document to what the teacher asks for. A useful record lets another person get started and find the evidence without you standing beside them.
Give the write-up time in your plan with the assignment milestone guide. If the build is getting too large, use the student project framework to narrow it. When you're ready to share, compare a video with a written blog format and pick the one that shows the work clearly.
0 Comments