Creating A Useful Readme.

Posted on Sat, 11/21/2020
2 minutes read

No one likes when you’re put on a new project and there is no straight forward way to get started. Don’t be a terrible person, make your README useful!

How do you make it useful? I like to think, “if I have never seen this project before what would I need to know” or “in two months what will I need to know and I’ve already forgotten it”. After thinking of that generally you’re going to come up with a couple question you should answer.

Information that should be present

  • What is this project?
  • How do I spin up this project?
  • Where are the environments this lives?
  • Are there designs?
  • Are there discovery docs or something useful that explains how things work?
  • Any useful “gotchas” with this?

Other nice things to do

README allows for Markdown so you should format things in an easy-to-read way.


# My Sample Website

- Staging Site: [](
- Git Repo: [](

## Getting Started

This site is a Symfony website, that is using a plugin to allow us to output it as a static website.

- `fin up`
- `fin composer install`
- `npm install`
- `npm run build`
- `npm run watch` - if desired

## Generating Static Site

- `fin build-static-site`
- `fin serve-static-site`

## Theming

│   │
│   └───js
|   |   main.js
│   |
│   └───scss
│       │   styles.scss
|       |
│       └───components
|           your new components go here
|   base.html.twig

│   │
│   └───images

All twig templates go into the `templates` directory, you can create sub directories or place
right in there. Site seems it will be small enough we can just place straight in there. You should
also make a matching scss file for that component in the `resources/scss/components` directory.
You will also need to add your component to the base `styles.scss`

To add new components on the page edit `base.html.twig` include it and pass in all the variables needed.

{% include "header.twig" with {
  'title': 'Hello World'
} %}

Adding assets like extra images, css, or js can be done with `{{ asset('/path/from/public/dir') }}`.

There will be need for using things like `<picture>` for responsive images.

## Deploying

This project follows our standard git flow and will deploy to staging with RC-vXXXX tags and for Prod we will be using RELEASE-vXXXX tags.

## Designs

![Desktop](assets/desktop.jpg "Desktop")
![Mobile](assets/mobile.png "Mobile")

## Team Leads

- Lead Developer: Josh Fabean
- Project Manager: Jash Fabean
- Designer: Anyone BUT Josh Fabean