Documenting Your Work
If AI meaningfully shaped your research, you should be able to say how. That’s not only a matter of honesty towards readers (Hosseini et al. 2023): it’s what lets you check your own work, repeat it, fix it when something goes wrong, and describe it in a methods section. This page covers what to record and how to make the record easy to keep.
The Gemini Notebook activity showed why this matters. The tool produced a good data file, but afterwards, it was impossible to determine exactly how: the code it ran wasn’t visible, its own account of its steps didn’t match what it had done, and a second run gave different data. Documentation can’t fix all of that, but it can make sure that your part of the process is never a mystery.
Reasons to Document
- Transparency: readers, reviewers, instructors, and collaborators can see what the AI did, and judge your results accordingly.
- Reproducibility: you, or someone else, can repeat the process, or at least understand why repeated results came out differently.
- Troubleshooting: when a result looks wrong months later, you can find where it came from.
- Acknowledgement: a record makes it easy to write an accurate disclosure statement or methods paragraph (see Acknowledging AI Use).
- Your future self: six months from now, you won’t remember which summary came from a model, which prompt worked, or what you checked.
Proportionality
The key principle to follow, as far as documentation is concerned, is proportionality: the more your research depends on it, the more you should document.
- Casual help such as brainstorming search terms, or rephrasing a sentence in your notes, needs little or nothing, a line in a research log is plenty.
- Substantive help such as a summary you rely on, a translation draft, or code for your analysis, needs a short entry: what you asked for, what you got, and what you checked.
- Anything that becomes data or evidence such as an extraction, a classification, counts, or a dataset, needs a full record: the tool and version, the exact prompts or code, the outputs themselves, and how they were verified.
A Documentation Template
One template covers most cases. Fill in as much as the stakes require.
| Field | What to write |
|---|---|
| Tool and model | The product (ChatGPT, Claude, Gemini Notebook) + model name and version (if known) |
| Date | When you used it (tools and models change, often without notice (Chen et al. 2024)) |
| Material | What you supplied: which documents, notes, data, or code |
| Purpose | What you were trying to do: summarize, brainstorm, extract, translate, write code |
| Prompts | The prompts themselves, or for a long conversation, a summary and the key prompts |
| Output | What you got, and where it’s saved (a file, a copied answer, a link to the conversation) |
| Verification | What you checked, and how: against the source, by hand on a sample, by rerunning, in another tool |
| Use | What happened to the output: discarded, revised, used as leads, incorporated into your notes, used as data |
| Disclosure | How you acknowledged it, if at all |
This is a record of method, not a citation format. Acknowledging AI Use covers what to say publicly, this record is what you’ll draw on when you do.
Explicit Processing: Requesting the Script
When you ask an AI tool to do something to your data (count, sort, extract, convert, clean), many tools now write and run a small program behind the scenes, and show you only the result. You get an answer, but not the procedure that produced it.
A better habit is to ask for the script. Instead of How many letters did Stevenson write each year?, ask Write a Python script that counts the letters per year in letters_metadata.csv. Then run the script yourself (Coding with LLMs, in Unit 3, shows how), and keep it alongside your results.
- Ideally, you would read the script and check that it does what you asked. Even without much programming experience, you can often follow the logic, especially if you ask the LLM to explain it line by line.
- Even if you can’t fully check it, keep it. The script is an exact, runnable record of what was done to your data. You can rerun it on new data, and get the same result every time. Someone who can read code can check it for you. And when a result looks wrong, the script is where you’ll find out why.
Compare that with the Gemini Notebook exports: the tool ran code, but you couldn’t see it, and when asked for its steps, it produced a script that didn’t reproduce its own result. A script you asked for, ran, and saved doesn’t have that problem.
Examples
A Log Entry for Chat-Assistant Use
Suppose you’ve done the letter exercise in this unit, and used the resulting table in your notes:
| Field | Entry |
|---|---|
| Tool and model | Claude (web chat), model shown as “Claude Sonnet” |
| Date | 3 October 2026 |
| Material | One letter: Stevenson to Sidney Colvin, August 1877 (wikisource_vol1_ch3_letter14.txt) |
| Purpose | List the people, places, and organizations mentioned |
| Prompts | Structured extraction prompt (saved in prompts/colvin_letter.txt), then three follow-ups about Villon, CORNHILL, and TEMPLE BAR |
| Output | A table of 10 rows, saved in notes/colvin_letter_entities.csv |
| Verification | Checked every row against the letter, and against two people’s annotations. Removed Villon and Sire de Maletroit (titles of works, not people). Stephen identified as Leslie Stephen from outside knowledge: confirmed in the Cornhill’s history |
| Use | Corrected table incorporated into my notes on Stevenson’s editors |
| Disclosure | Not yet, would need a note if the table is published |
A Methods Paragraph for a Pipeline
For the programmatic approach in Unit 3, the record is mostly the code and data themselves, and the documentation becomes a methods paragraph like this one:
Named entities (people, places, and organizations) were extracted from 462 letters with the pre-trained model
Davlan/bert-base-multilingual-cased-ner-hrl(Hugging Face Transformers 5.19.0, simple aggregation, long letters read in overlapping 512-token windows), after converting ALL-CAPS words to title case. To evaluate the extraction, two annotators independently annotated eight letters (Cohen’s kappa 0.89). Against the first annotator’s annotations, the model achieved F1 scores of 0.63 for people, 0.82 for places, and 0.48 for organizations. Its most common errors were names cut off or run together at the wrong point (R. L. SforR. L. S.), and words tagged as people that aren’t, such asGodandClever. The code, data, and annotations are available at [repository link].
Every number in it can be checked, and every step can be rerun. That’s the standard to aim for when AI output becomes research data.
- Keep a running log: a simple document or spreadsheet with the columns of the template. A few lines per session is enough for most use.
- Save the conversations that matter. Most chat tools can share or export a conversation, save a copy or a link with your notes, since histories can be deleted or changed.
- Save prompts beside what they produced: in a text file next to the output, in a comment in your code, or in a text cell of a notebook.
- Save the outputs you actually used, not just your edited version: you may need to show what the tool gave you.
- Date your files, and note model names and versions whenever the tool shows them.
Exercise
Write a log entry, using the template, for what you did in steps 1 to 4: the prompts, the tools, the table, and what your check in step 4 found. Use the example above as a model, but write down what you actually did, including what you’d change.
Then ask yourself: if you came back to this in a year, could you tell from your entry exactly how the table was made, and how far to trust it?
With a record of what you did, the next question is what you should say about it, and when. The AI-Assisted Work activity takes that up through six scenarios.
Key Takeaways
- If AI shaped your research, you should be able to describe how: what tool and model, when, on what material, with what prompts, and what you checked.
- Document in proportion to how much your research depends on the output.
- When AI processes your data, ask for the script rather than the result, run it yourself, and keep it.
- A good record makes acknowledgement, methods writing, and troubleshooting straightforward.
If you want to read more, the following are a good place to start:
- Hosseini et al. (2023): an essay on why, and how, researchers should disclose their use of AI tools, written for a general academic audience.
- Sandve et al. (2013): ten short rules for keeping computational work reproducible, from recording every step to keeping the exact versions of tools. Most apply just as well to work with AI tools.