Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 3 Next »

A very (VERY) brief overview of what should (probably) go in a readme file

Root README file

Important status messages

  • Usually in the form of shields/badges
  • Shows status like builds passing/failing, code coverage, latest version etc
  • 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:

# 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"`

  • No labels