diff --git a/packages/botonic-plugin-contentful/README.md b/packages/botonic-plugin-contentful/README.md
index e0f544c9d8..5bf13617ec 100644
--- a/packages/botonic-plugin-contentful/README.md
+++ b/packages/botonic-plugin-contentful/README.md
@@ -298,3 +298,28 @@ To define an empty day (such as bank holidays), just create the _Day Schedule_ b
 
 **Exceptional Schedule**
 For days with exceptional schedule (such as sales days), create the _Day Schedule_ and specify the special _Hour range_.
+
+# Extending this plugin
+
+## How to add a new TopContent
+- Don't panic. You can take [this](https://github.com/hubtype/botonic/pull/1417) as an example
+- Add enum entry to NonMessageTopContentType or MessageTopContentType
+- Implement a content class derived from TopContents to contents.ts
+- Add the new model to QA contentful space. To test custom fields, add a string
+field named "customFieldText"
+- Implement a delivery function to CMS interface
+- Implement a class derived from TopContentDelivery in src/contentful/contents
+- Integrate the previous class in ManageContentful as done for other types
+- Implement a delivery function to all classes that implement CMS interface
+- Implement a <NewContent>Builder class derived from TopContentBuilder in src/cms/factories/content-factories.ts.
+  Implement a Rnd<NewContent>Builder class derived from <NewContent>Builder at src/cms/test-helpers/builders.ts
+- Write integration tests using the builder classes in tests/contentful/contents which validates delivery of:
+  1. Minimal content (all content's optional fields in blank)
+  2. Full content. All content's optional fields filled. For complex contents, you may need
+     different tests for each subcase.
+  3. In contentful.com, add to the new model a text field named customFieldText.
+     Fill the customFields on one of the tests contents. Write a test which validates that when
+     delivered, the content common.customFields field only contains the field "customFieldText"
+- Add new field types to CONTENT_FIELDS in manage-cms/fields.ts
+    
+
diff --git a/packages/botonic-plugin-contentful/src/cms/contents.ts b/packages/botonic-plugin-contentful/src/cms/contents.ts
index 879ea0671a..cf71f9e37d 100644
--- a/packages/botonic-plugin-contentful/src/cms/contents.ts
+++ b/packages/botonic-plugin-contentful/src/cms/contents.ts
@@ -33,12 +33,13 @@ export class Asset {
 }
 
 /**
- * Any content deliverable from a CMS
+ * Any content deliverable from a CMS.
+ * They are immutable, which allows sharing and caching them.
  */
 export abstract class Content implements Stringable {
   protected constructor(readonly contentType: ContentType) {}
 
-  /** @return message if any issue detected */
+  /** @return error message if any issue detected */
   validate(): string | undefined {
     return undefined
   }
@@ -157,7 +158,6 @@ export abstract class MessageContent extends TopContent {
 /**
  * When any {@link keywords} is detected on a user input, we can use display the {@link shortText} for users
  * to confirm their interest on this content
- * TODO move contentId o ContentType here?
  */
 export class CommonFields implements Stringable {
   readonly shortText: string
diff --git a/packages/botonic-plugin-contentful/src/cms/factories/content-factories.ts b/packages/botonic-plugin-contentful/src/cms/factories/content-factories.ts
index a99d661f16..0f0319c5b2 100644
--- a/packages/botonic-plugin-contentful/src/cms/factories/content-factories.ts
+++ b/packages/botonic-plugin-contentful/src/cms/factories/content-factories.ts
@@ -12,6 +12,11 @@ import {
   Text,
 } from '../contents'
 
+/**
+ * Builder for Contents (which are immutable) which allow:
+ * - Setting the optional fields individually and in any order
+ * - Easing the implementation of the RndXXXBuilder classes at src/cms/test-helpers/builders.ts
+ */
 abstract class ContentBuilder {
   protected constructor(public id: string, public name: string) {}
 
@@ -28,9 +33,6 @@ abstract class ContentBuilder {
   abstract build(): Content
 }
 
-/** @deprecated use ContentBuilder */
-export type ModelBuilder = ContentBuilder
-
 export abstract class TopContentBuilder extends ContentBuilder {
   shortText?: string
   keywords: string[] = []
diff --git a/packages/botonic-plugin-contentful/src/cms/test-helpers/builders.ts b/packages/botonic-plugin-contentful/src/cms/test-helpers/builders.ts
index f7e0535acf..357785d0e6 100644
--- a/packages/botonic-plugin-contentful/src/cms/test-helpers/builders.ts
+++ b/packages/botonic-plugin-contentful/src/cms/test-helpers/builders.ts
@@ -20,6 +20,12 @@ import {
   TopContentId,
 } from '../index'
 
+/**
+ * The Builder classes below create Content instances with minimal effort
+ * to speedup the implementation of unit tests by setting random values for the
+ * non specified fields.
+ * They are exported by the plugin so that the can be used in bots' unit tests
+ */
 export function rndStr(): string {
   return Math.random().toString()
 }
diff --git a/packages/botonic-plugin-contentful/src/manage-cms/fields.ts b/packages/botonic-plugin-contentful/src/manage-cms/fields.ts
index 5943189796..093758c795 100644
--- a/packages/botonic-plugin-contentful/src/manage-cms/fields.ts
+++ b/packages/botonic-plugin-contentful/src/manage-cms/fields.ts
@@ -186,6 +186,10 @@ export class I18nField {
   constructor(readonly name: ContentFieldType, readonly value: string) {}
 }
 
+/**
+ * Only contains i18nalizable fields (used by tools to detect which fields need to be imported/deleted)
+ * TODO add all fields
+ */
 const FIELDS_PER_CONTENT_TYPE: { [type: string]: ContentFieldType[] } = {
   [ContentType.BUTTON]: [ContentFieldType.TEXT],
   [ContentType.CAROUSEL]: [],
@@ -199,6 +203,10 @@ const FIELDS_PER_CONTENT_TYPE: { [type: string]: ContentFieldType[] } = {
   [ContentType.URL]: [ContentFieldType.URL],
 }
 
+/**
+ * Adds common fields to FIELDS_PER_CONTENT_TYPE
+ * IMPORTANT @see FIELDS_PER_CONTENT_TYPE
+ */
 export function getFieldsForContentType(
   contentType: ContentType
 ): ContentFieldType[] {