Writing a README

2026-02-16 01:25:55 PST

Bart Massey 2026-02-16

The Art of the README is not really that dark an art. Let's talk about how to write one in current times.

• A modern README is in Github-Flavored Markdown (even if it is not in Github).

• The first line should be the name of the project and a one-line description.

  Myproject: my little example project

• The second line should always be your name and the date the README was created (do not update this).

  Copyright © 2026 Firstname McLastname

  Note that this is formatted as a copyright notice. This is probably a good thing. But I usually just go with informal.

  Firstname McLastname 2026

• Then a brief description of what the thing in the repo is and does.

  Myproject is a useless piece of code that frobnicates
  widgets. It is fast, and nothing like [Otherproject]()
  that also frobnicates widgets.

  Use hyperlinks where appropriate. It's really helpful.

• Give "build-and-run" instructions. Make sure that they are clear to someone with only a little knowledge.

  ## Build and Run
  
  Compile with `make PFLAGS=-DXXX`. Run with `./myproject`.

  Include installation instructions if needed and desired.

• Put a license file in LICENSE.txt so that people can use your stuff. Then add license info to the README.

  ## License
  
  This work is made available under the "Luxury Open
  Abomination License". Please see the file `LICENSE.txt` in
  this repository for license information.

  My apply-license can be helpful in quickly setting up common licenses.

• Add some acknowledgements. Ack anything and everything you can think of. It can't hurt, and makes people happy.

  ## Acknowledgements
  
  Thanks to my Mother for raising me. Thanks to Jane for
  proofreading, and Alice for the cool library I used.

Take a look at my Github for a whole bunch of good and less-good examples.

None of this is too hard or time-consuming. But it sure helps those who come to your project.