Comprehensive Readme

Have you ever tried to get a good understanding of a project but found it was completely lacking any sort of meaningful documentation?

To speed up the process of new developer onboarding (And refreshing myself on how past projects work) I set out to create a comprehensive readme written in markdown. Below is the current iteration I use on all my new projects to highlight how code should be written, what tooling is used to get set up, and how to deploy.

# SITE NAME / URL
Please read through the guidelines below to ensure the code is consistent and cohesive.

----

## Site URLs

### Live

### Staging

----

## HTML

How should the HTML be written?
This can be a link to your company handbook containing code standards documentation.

----

## CSS

How should the CSS be written?
This can be a link to your company handbook containing code standards documentation.

----

## Javascript

How should the JavaScript be written?
This can be a link to your company handbook containing code standards documentation.

----

## Media

Considerations for media.
- What folder is media kept in.
- Is compression handled in the application or on export?

----

## Fonts

Where are fonts served from?

----

## Performance

What mesures are in place to optimise performance?

----

## Accessibility

What mesures are in place to optimise accessibility?

----

## Tooling

What tools the project uses.

----

## Version Control

Information about version control (Git repository link etc..).

----

## Support and Optimisation

Browser support for this specific project.

----

## Localisation

Localisation for this specific project.

----

## Deployment/Integration

Notes about what tools are used to deploy to the staging and production environment.

----

## Documentation

A reminder that most documentation can be found in this readme. Link out to a handbook or other tech resource if you have one.

----

## Styleguide

If this project comes with a styleguide, detail how to access it.

---

## Other

Feel free to add your own if you need more headings.

Of course a lot of these things won't apply to every project which I why I haven't numbered the sections, so chop and change as needed.

What do you include in your readme?

This is just a high level view of what could be added to a readme to help new people to your project. Feel free to let me know what you include in yours via Twitter @graphicscove