diff --git a/README.md b/README.md
index c00f5ed7..91363f69 100644
--- a/README.md
+++ b/README.md
@@ -22,10 +22,10 @@ Example:
 
 ```xml
 <com.prolificinteractive.materialcalendarview.MaterialCalendarView
+    xmlns:app="http://schemas.android.com/apk/res-auto"
     android:id="@+id/calendarView"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
-    xmlns:app="http://schemas.android.com/apk/res-auto"
     app:mcv_showOtherDates="all"
     app:mcv_selectionColor="#00F"
     />
@@ -71,6 +71,11 @@ but we base it on tile size instead of an aspect ratio.
 The exception being that if a `tileSize` is set,
 that will override everything and set the view to that size.
 
+Documentation
+-------------
+
+Make sure to check all the documentation available [here](docs/README.md).
+
 Customization
 -------------
 
@@ -79,11 +84,12 @@ One of the aims of this library is to be customizable. The many options include:
 * [Define the view's width and height in terms of tile size](docs/CUSTOMIZATION.md#tile-size)
 * [Single or Multiple date selection, or disabling selection entirely](docs/CUSTOMIZATION.md#date-selection)
 * [Showing dates from other months or those out of range](docs/CUSTOMIZATION.md#showing-other-dates)
-* [Setting the first day of the week](docs/CUSTOMIZATION.md#first-day-of-the-week)
-* [Show only a range of dates](docs/CUSTOMIZATION.md#date-ranges)
+* [Setting the first day of the week](docs/CUSTOMIZATION_BUILDER.md#first-day-of-the-week)
+* [Show only a range of dates](docs/CUSTOMIZATION_BUILDER.md#date-ranges)
 * [Customize the top bar](docs/CUSTOMIZATION.md#topbar-options)
 * [Custom labels for the header, weekdays, or individual days](docs/CUSTOMIZATION.md#custom-labels)
 
+
 ### Events, Highlighting, Custom Selectors, and More!
 
 All of this and more can be done via the decorator api. Please check out the [decorator documentation](docs/DECORATORS.md).
diff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.md
index bda4995c..3dd2b201 100644
--- a/docs/CUSTOMIZATION.md
+++ b/docs/CUSTOMIZATION.md
@@ -3,10 +3,10 @@ Customization Options
 
 ```xml
 <com.prolificinteractive.materialcalendarview.MaterialCalendarView
+    xmlns:app="http://schemas.android.com/apk/res-auto"
     android:id="@+id/calendarView"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
-    xmlns:app="http://schemas.android.com/apk/res-auto"
     app:mcv_showOtherDates="boolean"
     app:mcv_arrowColor="color"
     app:mcv_selectionColor="color"
@@ -16,9 +16,12 @@ Customization Options
     app:mcv_weekDayLabels="array"
     app:mcv_monthLabels="array"
     app:mcv_tileSize="dimension"
+    app:mcv_tileWidth="dimension"
+    app:mcv_tileHeight="dimension"
     app:mcv_firstDayOfWeek="enum"
     app:mcv_leftArrowMask="drawable"
     app:mcv_rightArrowMask="drawable"
+    app:mcv_calendarMode="mode"
     />
 ```
 
@@ -34,6 +37,10 @@ If a tileSize is set, that will override the `layout_width` and `layout_height`
 
 The view is 7 tiles wide and 8 tiles high (with the top bar visible).
 
+### Width and Height
+
+You also have the possibility to use `tileWidth` and `tileHeight` separately. I would recommend using either `tileSize` or, `tileWidth` and `tileHeight`.
+
 
 ## Date Selection
 
@@ -76,20 +83,6 @@ You can provide a custom color by setting `mcv_selectionColor` in xml, or by cal
 If you want more control than just color, you can use the [decorator api](DECORATORS.md) to set a [custom selector](CUSTOM_SELECTORS.md).
 
 
-## First Day Of The Week
-
-The default first day of the week is Sunday. You can set a custom day of the week by setting `mcv_firstDayOfWeek` in xml, or by calling `setFirstDayOfWeek()`.
-The xml attribute is an enum of `sunday` through `saturday` and `setFirstDayOfWeek()` accepts values from `java.util.Calendar` such as `Calendar.MONDAY`.
-
-
-## Date Ranges
-
-By default, the calendar displays months for 200 years before today and 200 years after.
-You can specify different minimum and maximum dates by calling `setMinimumDate(CalendarDay)` and `setMaximumDate(CalendarDay)`.
-Passing `null` will reset back to the default 200 years.
-There are also convenience methods that accept a `Calendar` or a `Date` object and convert them to a `CalendarDay` using the relevant `CalendarDay.from()` factory method.
-
-
 ## Topbar Options
 
 ### Visibility
@@ -147,4 +140,4 @@ There are three different text appearances you can set:
 The header text appearance is used for the topbar month label.
 The weekday is for the row of weekday labels, and date is for the individual days.
 
-For date text appearance, make sure you respond to presses and states. [Read more here](CUSTOM_SELECTORS.md).
+For date text appearance, make sure you respond to presses and states. [Read more here](CUSTOM_SELECTORS.md).
\ No newline at end of file
diff --git a/docs/CUSTOMIZATION_BUILDER.md b/docs/CUSTOMIZATION_BUILDER.md
new file mode 100644
index 00000000..01621101
--- /dev/null
+++ b/docs/CUSTOMIZATION_BUILDER.md
@@ -0,0 +1,50 @@
+State builder
+=============
+
+Certain parameters are only modifiable using the state builder of the `MaterialCalendarView`.
+Using the builder prevents from updating the view each time one of the setters is called. The view is updated when calling `Builder#commit()` and that improve performances.
+Previously, the fields could be customize using casual setters.
+
+Here is a concrete example of how to use the builder:
+
+```java
+mcv.state().edit()
+   .setFirstDayOfWeek(Calendar.WEDNESDAY)
+   .setMinimumDate(CalendarDay.from(2016, 4, 3))
+   .setMaximumDate(CalendarDay.from(2016, 5, 12))
+   .setCalendarDisplayMode(CalendarMode.WEEKS)
+   .commit();
+```
+
+## state.edit() vs newState()
+
+Using `mcv.state().edit()` will preserve the current state of the `MaterialCalendarView` while `mcv.newState()` will initialize the builder with new parameters.
+Only the fields that are modifiable using the builder can be reset or edit. Here is the list of the fields:
+
+- First Day Of Week
+- Minimum Date
+- Maximum Date
+- Calendar Display Mode
+
+As an example, if you are setting `firstDayOfWeek` inside your xml, and you want to preserve the field when using the builder, you should use `state.edit()`.
+However if you don't want to preserve any current parameters from the list above, use `newState()`. In most cases `state.edit()` should be the right method to use.
+
+### First Day Of The Week
+
+The default first day of the week is Sunday. You can set a custom day of the week by setting `mcv_firstDayOfWeek` in xml, or by calling `setFirstDayOfWeek()`.
+The xml attribute is an enum of `sunday` through `saturday` and `setFirstDayOfWeek()` accepts values from `java.util.Calendar` such as `Calendar.MONDAY`.
+
+
+### Date Ranges
+
+By default, the calendar displays months for 200 years before today and 200 years after.
+You can specify different minimum and maximum dates by calling `setMinimumDate(CalendarDay)` and `setMaximumDate(CalendarDay)`.
+Passing `null` will reset back to the default 200 years.
+There are also convenience methods that accept a `Calendar` or a `Date` object and convert them to a `CalendarDay` using the relevant `CalendarDay.from()` factory method.
+
+### Calendar Display Mode
+
+`MaterialCalendarView` propose two display modes: weekly and monthly. You can set the display mode in your xml using the attribute `mcv_calendarMode` with `month` for monthly mode, or `week` for weekly mode.
+You can also use the builder `setCalendarDisplayMode(CalendarMode)` parameter.
+
+It is **important** to note that the `CalendarMode.WEEKS` is still experimental.
\ No newline at end of file
diff --git a/docs/CUSTOM_SELECTORS.md b/docs/CUSTOM_SELECTORS.md
index 679cc10a..fd0a1cab 100644
--- a/docs/CUSTOM_SELECTORS.md
+++ b/docs/CUSTOM_SELECTORS.md
@@ -73,7 +73,8 @@ Here's an example for a dark theme and a dark selector:
 <style name="CustomTextAppearance" parent="TextAppearance.MaterialCalendarWidget.Date">
     <item name="android:textColor">@color/my_date_text_color</item>
 </style>
-
+```
+```xml
 <!-- In res/color/my_date_text_color.xml -->
 <selector xmlns:android="http://schemas.android.com/apk/res/android">
 
diff --git a/docs/README.md b/docs/README.md
index 91d4b309..ee4468d5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,18 @@ This is where in depth documentation will be going.
 
 Check out most of the customization options [here](CUSTOMIZATION.md).
 
+## Customization using state builder
+
+Some of the customization can be made using a builder. Using a builder for those parameters helps preventing bugs and improves performances.
+Those parameters are:
+
+- [First Day Of Week](CUSTOMIZATION_BUILDER.md#first-day-of-the-week)
+- [Minimum Date](CUSTOMIZATION_BUILDER.md#date-ranges)
+- [Maximum Date](CUSTOMIZATION_BUILDER.md#date-ranges)
+- [Calendar Display Mode](CUSTOMIZATION_BUILDER.md#calendar-display-mode)
+
+The documentation is available [here](CUSTOMIZATION_BUILDER.md).
+
 ## Events, Highlighting, Custom Selectors, and More!
 
 All of this and more can be done via the decorator api. Please check out the [decorator documentation](DECORATORS.md).
@@ -18,4 +30,6 @@ Check out the [documentation for custom states](CUSTOM_SELECTORS.md).
 
 ## TODO
 
-Write and organize the documentation. Focus on customizability with real world scenarios.
+- Write and organize the documentation. Focus on customization with real world scenarios.
+- Improve performances.
+- Add test cases.
\ No newline at end of file