README's aren't just for repos

19 February 2025
notes

For those that write code often, a README is likely one of the first things you begin with when starting a new coding project, and one of the most frequently edited files as the project progresses. These files can outline the project in broad strokes and be short and sweet, or dive into incredible detail on all the configuration options available. Whichever route a maintainer chooses to go, one thing is for certain, README’s are worth their weight in gold.

Usually, when we think of writing documentation, we do it with an “end user” in mind. Some companies will do user stories envisioning what a particular person may wish to get done, and how they would go about doing it. However, we often overlook that for many systems or software that we have intensely customized, we are the biggest user. Even if you don’t code, if you configure something or customize it to your liking, you are now a system administrator for a userbase of one. Future you won’t have all the knowledge you do when you set something up, and so it makes a lot of sense to write yourself a README. In fact, it makes sense to write yourself many README’s. These README’s can be everywhere, not just in code repositories.

The “Root” README

A perfect place for the root README is in the base of your user directory. For Linux, this would be /home/name, for MacOS /Users/name. For Windows, this would be C:\users\name. The README can be written in any markup language, or no markup language at all. What matters is that it is easy to access and you know where it is.

The root README outlines in very broad strokes how you wish to keep things in order. The “project”, in this case, is all software that you have for that area of your life (probably best to keep your personal and work README separate). For example, it could start off like this:

# Overview

This file outlines how this system is setup, and how it interacts with others.

## Directories and files

Directories and files should use kebab case. If dates are used, they should follow the ISO 8601 standard.

There are 5 primary directories
  - `projects`
    Things that have a fixed start and end date. Directories over 6 months old are automatically flagged for review.
  - `areas`
    Persistant namespaces, mostly used for personal files generated by me.
  - `resources`
    Files from others that may be useful for reference in the future. Includes research papers.
  - `archive`
    Files that are legally necessary to keep, however should be removed from others to declutter.
  - `code`
    Exclusively contains git repositories.
    
## Task management

All tasks should be added and referenced in todo_app. Emails and GitHub issues are copied over to have a single source of truth.

## Backups

Backups are performed weekly on all files within `areas/backups` and `archive`. They go to backup_service, which has notifications if a backup is not done in 2 weeks.

Area specific README’s

Let’s say that you are using a cloud service to store some files, it may make sense to include a README in the base directory of that service. I won’t belabour the point with another long example, but it could be used to briefly describe how you use syncing, or when the contract renews.

# Cloud storage

This service holds personal files and is setup to 
automatically sync files from the home desktop and my laptop in real-time. 
It was purchased on a Black Friday sale and will renew for $100 in Dec 2026.

Or another one could be in a finance directory.

# Finances

This folder holds both budget information and tax documents. 
Taxes are done using some_tax_service and budgets are all created in 
some_budgeting_app. To file taxes, you will need the following forms:

1. Form A: Obtained from employer
2. Form B: Obtained from university

Before getting started:

1. Check email for donation reciepts. These will be tagged with `donation`

In the example above, the power comes from leveraging the knowledge you have immediately after filing your taxes to help your future self out. Similar to a new user approaching an unfamiliar tech stack, our knowledge will have atrophied. There are simply too many complex areas of life for us to be experts in everything all the time.

Writing a README also gives us time to reflect on how we want to do things, and if there is any difference between this and how things have already been done. By writing that we “backup weekly”, it forces a check to make sure that is actually the case, and documenting how exactly it is being done. Other areas, like standardizing file names, may feel daunting at first, but would get easier over time.

That’s it, that’s the post. Just an idea that I have been exploring and am excited about!

← Previous
Busywork