...
Important status messages
Usually in the form of shields/badges
Shows status like builds passing/failing, code coverage, latest version etc
Documentation links
If it’s a user-facing project, links to properly rendered documentation should be included
Developer installation
Everything required for a new developer to get started with a working dev environment
Should include key commands needed to build, debug, run etc
User installation (if relevant)
Often not required if the project is being deployed as part of a larger stack
If deployed to a package index (e.g. pip, nom, yarn etc) then a quick comment on how to install/use the library or application
Developer notes
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:
| Code Block |
|---|
# 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
...
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:
| Code Block |
|---|
### Build ARCHITECTURE.md
* Install `pipx`
* `pipx install archmd`
* `archmd . --out "ARCHITECTURE.md" --title="UKRDC-Nuxt Architecture"` |