diff --git a/README.md b/README.md
index b470b055b0620513042ebfaab841136472a23a74..c2748b1b71e0049e3d93be2d2a04c0059c4ba0ff 100644
--- a/README.md
+++ b/README.md
@@ -17,3 +17,11 @@ The API documentation is available at `<BASE URL>/swagger-ui.html`. A JSON versi
 * Sync backend with hand written Swagger specs;
 * Implement logout;
 * Update frontend (add introduction page, hide header/footer when not logged in, remove mock authors).
+
+### Maintenance
+
+* To keep an updated API documentation, the developers should keep synchronized both the auto-generated swagger file (from Java annotations) with the hand written one. You can follow this method to get a YAML description from the Java-annotated code:
+  * Add annotations to the Java code;
+  * Get JSON from `<BASE URL>/v2/api-docs`;
+  * Convert JSON to YAML on [http://jsontoyaml.com](http://jsontoyaml.com).
+  
\ No newline at end of file