Readme Files
- Joel Collins
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