diff --git a/architecture/services/organizations.md b/architecture/services/organizations.md
index caa7cbf82e7a6be5465d88006751426157c473f8..55e0fe762936c42b2dde0a60c7574cb448924287 100644
--- a/architecture/services/organizations.md
+++ b/architecture/services/organizations.md
@@ -15,7 +15,7 @@ The entrypoint of the service is a REST API provided by a [NestJS](https://githu
 
 ## API documentation
 
-NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-docs`.
+NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`.
 
 ## Service health
 
diff --git a/architecture/services/resources.md b/architecture/services/resources.md
index a23801efc9b7d5a16e971f746aa45ed2a62ca449..49867847a5404205e0e485aa39e19ff90c2b09cf 100644
--- a/architecture/services/resources.md
+++ b/architecture/services/resources.md
@@ -1,9 +1,12 @@
 # Resources service
 
-
-
 ## What it does
+This service can provide lists of resources and formats.  
+A resource is an entity representing some information, usually geographic, that can be accessed by a query (for example Web Map Service) or by downloading a file. One resource can be considered standard (e.g WMS protocol) or not standard (a custom service).  
+Each resource is associated with one or many formats.
 
+*Example:*  
+the output of a Web Feature Service (WFS), standard service providing an interface for geographical features, is a resource. And it is associated with many formats as such Shapefile or JSON.  
 
 ## How it works
 
@@ -14,7 +17,7 @@ The entrypoint of the service is a REST API provided by a [NestJS](https://githu
 
 ## API documentation
 
-NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-docs`.
+NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`.
 
 ## Service health