Skip to content

Instantly share code, notes, and snippets.

@cvuorinen
Created January 8, 2018 12:35
Show Gist options
  • Save cvuorinen/354160e232021479aa73f1046b0c5784 to your computer and use it in GitHub Desktop.
Save cvuorinen/354160e232021479aa73f1046b0c5784 to your computer and use it in GitHub Desktop.
README template

Project title

Short description about the project and it's purpose. Includes e.g. projects main goal, intended users, some history (if old project) etc.

Team

Project team and other people that are involved with the project.

Client

Name of the client and their contact persons

3rd parties / collaborators

Roles and responsibilities of any 3rd parties or other outside collaborators involved in the project.

Project status

Overview of project status at the time of writing (should be updated when status changes) and other notes that are relevant for any new person coming into the project.

E.g.

Initial production release was 1.1.2016 Deployments & maintenance outages must be planned beforehand with person X

Architecture

Overview of the system architecture and the environment it runs in (system requirements).

  • Server OS: e.g. CentOS 7
  • Programming language: PHP/Node.js/Python etc. + version
  • Framework: Zend Framework/Symfony/Express etc. + version
  • Database: MySQL/MSSQL/MongoDB etc. + version
    • Data model: link to ER diagram etc.
  • Other server applications: List of other server applications with versions.
  • Libraries/modules: List of used 3rd party libraries/modules/plugins etc. with versions. Can be a link to package.json or composer.json when applicable.
  • Frontend libraries: Same as above but for frontend code.

Directory structure

Any notes about projects directories (when not apparent or obvious otherwise).

Components / subprojects

Description of any components or subprojects (if project has any) and link to their documentation.

Servers

Description of projects servers, where are they hosted, who has access / where are credentials stored etc.

Background/cron jobs

List of background jobs that are executed periodically with a short description.

Integrations

Description of all external APIs or other integrations with 3rd party systems.

Installation

Installation instructions

Development

Description of the most important tools and conventions used during development.

E.g.

  • Code review: make a pull request against master and someone else will review and merge it
  • CI: e.g. Jenkins URL
  • Automated tests: e.g. what kind of tests there are and how to run them

Deployment

Description of the deployment process and the tools used.

Logs

Description and location of the logs that the system writes.

Security

Any special notes about security (last time someone went through security checklist, possible 3rd party security audits etc.)

Backups

Description of the system backups and who is responsible for them.

Monitoring

Description how the system is monitored and who is responsible for reacting on alerts. Overview of SLA if any.

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