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.

A Sample README

# My Sample Website


- Staging Site: [https://joshfabean.com](https://joshfabean.com)
- Git Repo: [https://git.joshfabean.com/fabean/drupal-config-split-sample](https://git.joshfabean.com/fabean/drupal-config-split-sample)


## 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


```
sample-website
│
└───resources
│   │
│   └───js
|   |   main.js
│   |
│   └───scss
│       │   styles.scss
|       |
│       └───components
|           your new components go here
│
└───templates
|   base.html.twig


└───public
│   │
│   └───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