Editing README Files and Project Notes

A README is the first file people read in a project. It explains what the project is and how to use it. It's usually written in plain text or Markdown, and it's easy to edit on the go.

What goes in a README

Section	What to write
Title	the project name
Description	one or two sentences on what it does
Installation	how to set it up
Usage	a simple example
Contributing	how others can help
Licence	the terms of use

A simple template

# Project Name

A short description of what this project does.

## Install
1. Download the files.
2. Run the setup command.

## Usage
Run the program and follow the prompts.

## Licence
MIT

Writing tips

1. Lead with the purpose. Say what it does in the first sentence.
2. Use short sentences.
3. Show an example. A small code sample teaches more than a paragraph.
4. Keep it current. Update it when the project changes.
5. Write for a newcomer. Assume they know nothing about the project.

Project notes

For your own projects, keep a plain-text notes file:

• What you did today.
• Ideas and to-do items.
• Problems and how you solved them.
• Commands you keep forgetting.

A dated log helps you resume after a break:

2027-03-01 Fixed the login bug. Next: test on phone.
2027-03-02 Added export feature.

Quick fixes on the go

A README often has a typo or an out-of-date link. A quick edit on your phone can fix it.

Formatting

Markdown is common in READMEs: a hash for headings, a hyphen for bullets and backticks around code. But a plain-text README with clear spacing works too.

Keep it findable

Name the file README or README.md, and keep it in the top folder of the project.

Future you

Notes you write today are for a stranger tomorrow, and that stranger is you in six months.

Get Notepad+ Text Editor →