Can I use ChatGPT to write my project README?

Many courses allow a draft after the code runs. Do not let the model invent frameworks, test counts, or design patterns you did not use. Graders open the repo.

What is wrong with AI code comments?

They narrate obvious lines (“increment i”) and skip the one decision that is actually tricky. Comments should explain why, not restate the syntax.

Should I humanize the code itself?

No. Humanize the README and a few necessary comments. Do not rename variables into purple prose or add comments that hide what the function does.

Where does Human Writes fit?

One voice pass on stiff setup prose after your run steps are true. It will not make a broken install command work.

Humanize a Student README (No Fake Complexity)

A student README is a map of the repo you actually submitted, not a startup landing page. ChatGPT writes the second thing: “robust, scalable, modular architecture” for a 200-line Flask app with one route.

Humanize the words after the commands are real. The code stays the code.

Hubs: humanize a README (professional install docs), ethical AI checklist, lab report.

What graders punish

Pattern	What they find when they clone the repo
“Microservices” for one file	A single `main.py`
Fake test badge	No `tests/` folder
Install steps for the wrong package manager	`npm` on a Python project
Comments on every line	Noise, plus a detector-shaped draft
Invented API keys or datasets	A project that cannot run

Lock the fact card

Field	Your entry
What it does in one sentence	e.g. CLI that sorts a CSV of courses by time
How you run it	Exact command you just ran
Dependencies	From your lockfile, not a guess
Files that matter	3–6 paths
Known limits	What you did not build
What you will not claim	Scale, security audit, ML model you did not train

Prompt: “Write a README from this card only. Sections: what it does, requirements, run, files, limits. No architecture essay. No badges I do not have.”

Comments worth keeping

Keep	Delete
Why a workaround exists	`// loop through array`
Units and edge cases	Restating the function name
License or citation the assignment requires	“This function is very important”
A tricky invariant	Comments in a language you do not submit

If the assignment says “comment your code,” comment decisions, then humanize only the sentences that sound like a press release.

Before and after

AI README opener:

This cutting-edge solution leverages a modern tech stack to deliver a seamless, enterprise-grade experience for managing student data at scale.

After the fact card:

course-sorter reads courses.csv and prints a weekly timetable. It uses the Python standard library only. Run python sort_courses.py courses.csv from the project folder. It does not check for room clashes.

Second version is what a marker can verify in two minutes.

README sections that earn their place

Use a short stack. Extra sections are where models invent a company.

Section	Include	Skip
What it does	One paragraph a marker can test	Vision and roadmap
Requirements	Language version you used	“Any modern OS”
Run	The command and a sample of real output, trimmed	A tutorial for the whole language
Files	The paths you want read first	Every asset in `node_modules`
Limits	Bugs you know about	A fake security review

If the assignment also asks for a reflection, keep that in a separate file. Mixing “what I learned” into the run steps makes the README harder to follow and easier to stuff with generic growth language.

For projects that include a short design note, see design doc. Leave the design decisions accurate. Humanize only the sentences around them.

Workflow

Run the project once and paste the real command output into your notes.
List files from the tree, not from memory of a tutorial.
Draft the README from the card.
One Human Writes pass on the prose sections. Leave commands in code blocks untouched.
Delete comments that only repeat the next line.
If the syllabus requires disclosure, say you used AI for the README wording. See the ethical checklist.

Marker’s five-minute test

Assume the marker clones the repo and does not read your reflection first. They will try the run command, open the file you named, and skim comments only where the code is surprising. Write for that pass:

The command in the README is the one in your last commit, including the filename.
A missing dependency is listed, not discovered from an error you already fixed on your machine.
Comments near a workaround say what broke, not “handles edge cases.”
Screenshots, if you include them, match the current UI. An AI image of a dashboard you did not build is a mismatch, not a decoration.

If that five-minute pass fails, another humanize pass will not save the grade. Fix the repo, then fix the sentences.

Bottom line

A student README should describe this repo. Lock the run steps and the limits, then polish voice. Human Writes helps the sentences. It does not invent a system you did not build.