diff --git a/docs/README.md b/docs/README.md
index 22f1116c8..b88cd50bb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,18 @@
 # Generating the documentation
 
-To generate the documentation, you first have to build it. Building it requires the package `sphinx` that you can 
+To generate the documentation, you first have to build it. Several packages are necessary to build the doc,
+you can install them using:
+
+```bash
+pip install -r requirements.txt
+```
+ 
+## Packages installed
+
+Here's an overview of all the packages installed. If you ran the previous command installing all packages from 
+`requirements.txt`, you do not need to run the following commands.
+
+Building it requires the package `sphinx` that you can 
 install using:
 
 ```bash
@@ -14,10 +26,35 @@ You would also need the custom installed [theme](https://github.com/readthedocs/
 pip install sphinx_rtd_theme
 ```
 
+The third necessary package is the `recommonmark` package to accept Markdown as well as Restructured text:
+
+```bash
+pip install recommonmark
+```
+
+## Building the documentation
+
 Once you have setup `sphinx`, you can build the documentation by running the following command in the `/docs` folder:
 
 ```bash
 make html
 ```
 
-It should build the static app that will be available under `/docs/_build/html`
\ No newline at end of file
+---
+**NOTE**
+
+If you are adding/removing elements from the toc-tree or from any strutural item, it is recommended to clean the build
+directory before rebuilding. Run the following command to clean and build:
+
+```bash
+make clean && make html
+```
+
+---
+
+It should build the static app that will be available under `/docs/_build/html`
+
+## Adding a new element to the tree (toc-tree)
+
+Acceptes files are reStructuredText (.rst) and Markdown (.md). Create a file with its extension and put it
+in the source directory. You can then link it to the toc-tree by putting the filename without the extension.
\ No newline at end of file
diff --git a/docs/source/_static/css/Calibre-Light.ttf b/docs/source/_static/css/Calibre-Light.ttf
new file mode 100644
index 000000000..2e6631909
Binary files /dev/null and b/docs/source/_static/css/Calibre-Light.ttf differ
diff --git a/docs/source/_static/css/Calibre-Medium.otf b/docs/source/_static/css/Calibre-Medium.otf
new file mode 100644
index 000000000..f9f11ebe4
Binary files /dev/null and b/docs/source/_static/css/Calibre-Medium.otf differ
diff --git a/docs/source/_static/css/Calibre-Regular.otf b/docs/source/_static/css/Calibre-Regular.otf
new file mode 100644
index 000000000..3801b704c
Binary files /dev/null and b/docs/source/_static/css/Calibre-Regular.otf differ
diff --git a/docs/source/_static/css/Calibre-Thin.otf b/docs/source/_static/css/Calibre-Thin.otf
new file mode 100644
index 000000000..44f93821e
Binary files /dev/null and b/docs/source/_static/css/Calibre-Thin.otf differ
diff --git a/docs/source/bertology.md b/docs/source/bertology.md
new file mode 100644
index 000000000..e408484e8
--- /dev/null
+++ b/docs/source/bertology.md
@@ -0,0 +1 @@
+# Bertology
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 978b20446..706329c19 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -41,7 +41,8 @@ release = u'1.0.0'
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'recommonmark'
 
 ]
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4b5b98214..8505d0f01 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -7,11 +7,14 @@ Pytorch-Transformers
     :caption: Notes
 
     installation
+    philosophy
     usage
     examples
     notebooks
     tpu
     cli
+    migration
+    bertology
     torchscript
 
 
diff --git a/docs/source/migration.md b/docs/source/migration.md
new file mode 100644
index 000000000..9165365fa
--- /dev/null
+++ b/docs/source/migration.md
@@ -0,0 +1 @@
+# Migration
\ No newline at end of file
diff --git a/docs/source/philosophy.md b/docs/source/philosophy.md
new file mode 100644
index 000000000..78c4f0309
--- /dev/null
+++ b/docs/source/philosophy.md
@@ -0,0 +1 @@
+# Philosophy
\ No newline at end of file
diff --git a/docs/source/torchscript.rst b/docs/source/torchscript.rst
index c94ce35fe..f5eb97f69 100644
--- a/docs/source/torchscript.rst
+++ b/docs/source/torchscript.rst
@@ -122,9 +122,4 @@ Using the traced model for inference is as simple as using its ``__call__`` dund
 
 .. code-block:: python
 
-    traced_model(tokens_tensor, segments_tensors)
-
-(Optional) Using TorchScript in C++
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Below are examples of using a model exported using Python in C++.
+    traced_model(tokens_tensor, segments_tensors)
\ No newline at end of file