Skip to content

Instantly share code, notes, and snippets.

@joesustaric
Last active June 28, 2021 02:39
Show Gist options
  • Save joesustaric/3df2e4809626ef31be5a7ac5da1cdeda to your computer and use it in GitHub Desktop.
Save joesustaric/3df2e4809626ef31be5a7ac5da1cdeda to your computer and use it in GitHub Desktop.
README.md for Enterprises

Readme Guide for Enterprise

Below is my example of a well structured Readme file for a code base maintained in an organisation. The ordering isn't that important but the information is. Linking out to other things can be ok although in my experience I believe things directly related to the code should live next to the code, including documentation.

FooBar

A short paragraph on what FooBar does. Be concise as possible.

Maintainers

Who owns FooBar or which team owns it? and/or Who knows the most about it? (link to contributors) or This code is unmaintained and looking for ownership.

Link to CI

Could be a badge image with last run status. Maybe even a short description of the pipeline or a link to the Pipeline as Code.

Deployment

How is this code deployed to all shared environments? If this repo includes DB changes, how do we manage and deploy migrations?

Architecture

What other systems does this code depend on? Diagram(s) are great here. (esp C4 model)

Architecture Decision Records

Link to ADRs. Helpful adr-tools.

Future State

What are the future (long and/or short term) goals of this code base? eg. Is this a monolith which we are modernising or breaking apart?

Development

How to set up a local environment or what has to be configured correctly.
How to run the tests locally.
Are there any (prefered automated) coding standards this repo uses?

Monitoring

Where do I go to get non prod / staging / production Logs? Oncall Information / Who supports the running of this application? How can someone get in touch with them?

Runbooks

Links to other documents on standard runbooks. eg. Rolling the db password. Debugging common issues. etc.

Contributing

If you want to change something in this repo, what should you do?

Alumni

This can be optional but sometimes it's nice to have a list of Alumni that have participated to writing and maintaining this code base. Shows care and pride in what you do.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment