How to Write a README File for Your Project Folders

Imagine opening a folder of files that you created years ago, or inherited from someone else. Names that once made sense are now cryptic, and you cannot tell which version is final or why a certain subfolder exists. A tiny text file placed at the top of the folder can solve most of these problems. It is often called a README, and it is one of the cheapest, most effective preservation tools available.

What a README Is

A README is a short document, usually plain text, that sits in a folder and explains it. It answers the questions that a future reader would ask: what is this, who made it, when and why, and how are the files organized? Because it is plain text, almost any program can open it, today and in the future.

Why Plain Text

Word processor files depend on particular software, and formatting can break. A plain text file with a simple name, such as README.txt, will open on practically any device. It contains no hidden features to go out of date. Keep the formatting simple: short lines, clear headings written in capital letters or with a few dashes and no special effects.

What to Include

You do not need a lengthy document. A good README for a family or personal project might contain:

Title and short description. One or two sentences on what the folder holds.
Who and when. The creator, the main dates and any other people involved.
Contents overview. A list of the main subfolders and what each contains.
File naming pattern. A line explaining how names are built, such as date first, then topic.
File formats and software. The types of files, and which programs were used to make them, with versions if you know them.
Known problems. Gaps, damaged files or uncertain dates.
Related material. Where backups or connected collections are stored.
Last updated. The date you last revised the README.

A Sample Shape

You might begin with a heading line such as 'Grandfather's Workshop Photographs, 1975 to 1990', followed by a paragraph describing the collection, who scanned it and when. Underneath, a short list can explain that the folders are organized by year, that file names begin with the year and month, and that the originals were scanned from prints at a particular resolution. A final line might note that two photos from 1982 are missing from the sequence.

Write for a Stranger

As with file names, imagine that your reader has no background. Define abbreviations. Spell out the full names of people at least once. Avoid phrases like 'the usual place' or 'the new version'. If a decision was made for a reason, write the reason in a sentence.

Keep It Next to the Files

A README works best when it travels with the folder. If you copy the folder to a backup, the note goes too. Resist the temptation to keep these notes in a separate system, where they can be lost or become out of step with the files.

Update It When Things Change

Whenever you add, remove or reorganize files, take a minute to adjust the README. Add a short line recording the change and the date. A brief history of changes is valuable for anyone who needs to trust the collection later.

Use It Alongside Your Other Records

A README complements your inventory and metadata habits. The inventory shows the big picture of your collections, as described in our guide on building a personal digital archive inventory, while a README gives local detail inside each one.

Avoid Sensitive Information

Do not put passwords, account numbers or private identification details in a README. If you must refer to protected material, say where the information is kept, such as in a password manager, rather than the secret itself.

Frequently Asked Questions

How long should a README be? As long as it needs to be, and no longer. Half a page is plenty for most folders.

Should every folder have one? No. Use them for main collections and projects, not for every subfolder.

Can I use a different file name? Yes, but a familiar name like README makes it easy to spot and is widely understood.