/
Readme Files

Readme Files

Owned by Joel Collins
Last updated: Mar 14, 2024
1 min read

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

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