Content Comparison

...

• Any extra quirks, environment setup notes etc

• Could include examples of IDE settings

• Could include notes on how to create or build auxiliary files such as rendered documentation

Nested README files

These are far less common, but in large projects can be incredibly useful. The idea here is to also include a README file in each folder within the repo, briefly explaining what that folder is for For example, in the UKRDC-Nuxt repo, we have a README file within our utilities folder containing:

# UTILITIES

This directory contains Javascript functions that are not bound to Vue components. 
For example, frequently-used functions for data parsing.

Combining into an ARCHITECTURE file

Especially for new developers, it can be really useful to combine each nested README file into a top-level ARCHITECTURE file. This effectively acts as a table-of-contents for your code.

For example, UKRDC-Nuxt has ukrdc-nuxt/ARCHITECTURE.md at main · renalreg/ukrdc-nuxt · GitHub

Creating this file manually can be tedious, so I’ve made a really hacky little tool to build an ARCHITECTURE file from your nested README files:

GitHub - jtc42/python-archmd: Python utility for building an architecture.md

Any projects using this library to generate architecture files should try to include a developer note in README explaining how to rebuild the file. For example:

### Build ARCHITECTURE.md

* Install `pipx`
* `pipx install archmd`
* `archmd . --out "ARCHITECTURE.md" --title="UKRDC-Nuxt Architecture"`