---
# System prepended metadata

title: The README Structure

---

Tagion README guideline

# The README Structure
##  Introduction
The README file may start with:
* The project logo. 
* TOC for easy navigation.
* The company intro (a link to a root repo with up-to-date descriptions). 

## The project overview
This section contains a clear overview of the project (description of what the project does to help potential users to clarify if they really need it).

## Headlines
The headlines have to be short, but at the same time informative, easy to read, and clear, like:
- ‘Getting started’
- ‘Architecture overview’
- ‘Contributors’
- and so on. 

It would be cool to avoid starting the sentence (headline) with a verb in imperative, like ‘Understand Tagion's Modular Structure’.
 Instead, we can use:
* How **to understand** Tagion's Modular Structure (infinitive)
* **Understanding** Tagion's Modular Structure (gerund)
* Tagion's Modular Structure 


## Naming
Names for repositories should be self-explanatory. There can be prefixes for repositories that explaining what they are, like:
* library - lib
* cli - cli
* test - test
* website - web
* documentation - doc

There is also needed one-liner (to end up with), explaining what the module does, like:
* web_home
* test_node 
* lib_secp256k1

## Images
All the images in the README file should be clean, clear, easy to read, and kept in a balance with the text information they illustrate. Certainly, it is not a good idea to decorate the file like a Christmas tree, but all the necessary images illustrating the appropriate text(s) have to be presented. All the screenshots in a file should be created in the same style.
Example:
![](https://i.imgur.com/RMiMm26.png)


## Usage
* Demo with clear screenshots or GIF (explaining how the project really works).
* Code examples
* Key Features 
## Installation guide
Clear step-by-step installation instructions for what should be installed with separate screenshots for each step.
# 
## Prerequisites
* Multiple ways to get started
* OS to use, that should be installed

## Development guide
...

## Related documentation
In case any other related detailed documentation is needed,  it’s better to insert a link for it into the README file. The README file has to be as short as possible, but as informative as necessary. 

## FAQ section
Section with frequently asked questions and answers.

## Contribution guide
A link for contributors’ documentation.

## Code of conduct
...

## Maintainers list 
List of links to github.com for the personalities to contact if needed like @username.

## License
The common way is to put the licenses at the very bottom, but in the case of a non-permissive license, this might actually be better to higher it up to prevent any [confusion](https:/github.com/hackergrrl/art-of-readme#cognitive-funneling/).

## Release notes
https://github.com/sschmid/Entitas-CSharp/releases - like this
* What's new (changelog)
* Breaking changes
* What’s fixed 

## The README key checkpoints
* Short explaining the purpose of the project
*  Necessary background context and  links for further reading (like project pages and related libraries)
*  Links to informative sources for terms the user may not be familiar with
*  A clear, working example of a module usage
*  Clear installation instructions
*  Extensive API documentation (a reference to docs)
*  Keep a balance with images to relay critical information
*  License

 

