Versions Compared

Version Old Version 4 New Version Current
Changes made by

Joel Collins

Joel Collins

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

...

Note

I would strongly suggest also creating a Confluence space (for larger projects) or page (for smaller projects) with keywords and links out to the project README. For example UKRDC Dashboard - Confluence (atlassian.net)

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:

# 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:

...