chore(markdown): add some docs

Signed-off-by: Protocole <[email protected]>

Author: alexandrebrg

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to your application
+
+To contribute to this project, you should be aware of the project folder architecture and some other rules that are in place.
+
+## Folder architecture
+
+**The source code of the project is located in the `src/` folder.**
+
+```
+src
+├── main
+└── resources
+```
+
+
+### Configuration loader files
+`src/main/configuration` will contain config and module loaders.
+
+### Application configuration files 
+`src/resources` contains configuration files for each environment (don't put any
+secret there)
+
+## File naming convention
+
+Each file must be suffixed by the name of what it contains.
+
+For example, if you want to create a custom decorator, you'll put the file into the `decorators` folder of your module with the following name `mydecorator.decorator.ts`.
+
+It is important because we can identify more easily files during debugging phases.
+
+## Conventional commits
+
+As a base, take [conventional commits by Angular](https://www.conventionalcommits.org/en/v1.0.0-beta.4/), and then
+customize to fit your needs.

README.md

@@ -1,6 +1,29 @@
 # NestJS Microservice boilerplate
 
-TODO
+## Getting started 
+
+In order to run the application: 
+
+```
+npm ci 
+npm run start:dev
+```
+
+You should have the appropriate configuration and services running on your machine 
+in order to ensure the application is launching properly.
+
+## Telemetry 
+
+This application is based on [@opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js/),
+so metrics and traces are generated through it. Moreover, logs (in production
+environment) have fields (`trace.id` and `span.id`) in order to correlate logs 
+with traces. You can find the configuration files for tracing in [`tracing.config.ts`](./src/main/configuration/tracing.config.ts).
+**When forking the boilerplate, you should update [`tracing.config.ts:12`](./src/main/configuration/tracing.config.ts#L12) 
+to match your service.**
+
+Learn more about how you can use spans in your code with [nestjs-otel](https://github.com/pragmaticivan/nestjs-otel). 
+And more globally, to learn about telemetry, see this [CNCF](https://github.com/cncf/tag-observability/blob/main/whitepaper.md)
+article.
 
 ## Configuration