The README file describes the essence of the project playing the most important role. Most visitors will simply scroll down about twice on the README and leave if they are not interested. So, the README file should provide the reason why to checkout your project!!!). Bearing that in mind, your job is to:
- Tell them what it is (with context).
- Show them what it looks like in action.
- Show them how they use it.
- Tell them any other relevant details.
Your readers will most likely view your README in a browser so please keep that in mind when formatting its content:
- Use proper format when necesary (e.g.:
import pandas as pd
). - Categorize content using two or three levels of header beneath.
- Make use of emphasis to call out important words.
- Link to project pages for related libraries you mention. Link to Wikipedia, Wiktionary, even Urban Dictionary definitions for words of which a reader may not be familiar. Make amusing cultural references.
- Add links to related projects or services.
Last but not least, by writing your README soon you give yourself some pretty significant advantages. Most importantly, youβre giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included.
Self-explanatory names are best. If the name sounds too vague or unrelated, it may be a signal to move on. It also must be catchy. Images, Logo, Gif or some color is strongly recommended.
Alpha, Beta, 1.1, Ironhack Data Analytics Final Project, etc... It's OK to write a sentence, too. The goal is to let interested people know where this project is at.
Having a one-liner that describes the pipeline/api/app is useful for getting an idea of what your code does in slightly greater detail.
Python, Pandas, Scipy, Scikit-learn, etc. Indicate the technological nature of the software, including primary programming language(s), main libraries and whether the software is intended as standalone or as a module in a framework or other ecosystem.
Why does it exist? Frame your project for the potential user. Compare/contrast your project with other, similar projects so the user knows how it is different from those projects. Highlight the technical concepts that your project demonstrates or supports. Keep it very brief.
Requeriments, prerequisites, dependencies, installation instructions.
Parameters, return values, known issues, thrown errors.
βββ project
βββ __trash__
βββ .gitignore
βββ .env
βββ requeriments.txt
βββ README.md
βββ main_script.py
βββ notebooks
β βββ notebook1.ipynb
β βββ notebook2.ipynb
βββ package1
β βββ module1.py
β βββ module2.py
βββ data
βββ raw
βββ processed
βββ results
Do not forget to include
__trash__
and.env
in.gitignore
Next steps, features planned, known bugs (shortlist).
Credits, alternatives, references, license.
Getting help, getting involved, hire me please.
Here you have some repo examples:
Here you have some tools and references: