Repository Style Guide¶
A document to make your READMEs look cool.
Description¶
This is a guide to make our repository documentation clear, useful, and stylish. ✨
Difference with the General Guide¶
The main difference between this guide and the general guide is how we handle the main title. For the cover of a repository (a README.rst), we want it to be love at first sight, so we use a simpler and more direct style:
The main title is only underlined with =======. No double line above!
We do not use a formal subtitle. Instead, we place a short and catchy paragraph that describes the project.
This format is cleaner and more minimalist, perfect for people to know what your project is about instantly. For everything else (lists, links, tables, etc.), we follow the general guide rules.
Recommendations¶
Suggested Sub-titles¶
Here is a list of sub-titles we recommend using in your READMEs. They are like the ingredients of a good recipe!
- Description:
This is where you tell what your amazing project is about. Show off your work!
- Prerequisites:
What is needed for your project to work? Say it here, straightforwardly.
- Procedure/Instructions:
The step-by-step guide for people to use your creation. Nobody likes 300-page manuals!
- Problems/Issues:
Are there known issues or “workarounds”? This is the place to confess them. 😉
- Participation:
How can people help you make your project even cooler?
- Contact:
Leave your social media, an email, or where people can find you to grab a coffee (virtual or real).