diff --git a/.gitignore b/.gitignore
index 9cdbd1b04e3227442af0509adf7ced42411b266e..237f22268a5c24f4d81392e395d893b5af770b60 100644
--- a/.gitignore
+++ b/.gitignore
@@ -64,6 +64,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/flatland*.rst
+docs/modules.rst
+docs/changelog.md
+docs/flatland_2.0.md
 
 # PyBuilder
 target/
@@ -112,4 +116,4 @@ ENV/
 images/test/
 test_save.dat
 
-.visualizations
\ No newline at end of file
+.visualizations
diff --git a/Makefile b/Makefile
index 625146c06526b97f607b2d33a81bfc2b2f67ceb2..c84991f6757fafa0ef6198205bcf92d886a0e060 100644
--- a/Makefile
+++ b/Makefile
@@ -69,7 +69,7 @@ coverage: ## check code coverage quickly with the default Python
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/flatland*.rst
 	rm -f docs/modules.rst
-	sphinx-apidoc --force -a -e -o docs/ flatland
+	sphinx-apidoc --force -a -e -o docs/ flatland -H "Flatland Reference"
 	$(MAKE) -C docs clean
 	cp *.md docs
 	$(MAKE) -C docs html
diff --git a/changelog.md b/changelog.md
index aad11d3d806e18a17246eff86d6a8a236994b8e8..91e1ab6181ad1c7cd5b28e9ee06711ecd837324a 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,5 @@
-Keeping track of major Flatland Changes
-=======================================
+Changelog
+==========
 
 Changes since Flatland 0.3
 --------------------------
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 45f577275202f200877dbf9904ebe51bd41bbf0a..31c10fe939e3bd5c582a7fdc4123c00925c1a734 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -41,7 +41,8 @@ Frequently Asked Questions (FAQs)
     .. _importlib-resources: https://importlib-resources.readthedocs.io/en/latest/
 
     Renders the scene into a image (screenshot)
+
     .. code-block:: python
 
-    renderer.gl.save_image("filename.bmp")
+        renderer.gl.save_image("filename.bmp")
 
diff --git a/docs/index.rst b/docs/index.rst
index c38b78b5073f4c7830dd13b110f9a6f452171ba1..f644f73e56b74ee5ea765e15d3ed5bef832614e9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,13 +11,14 @@ Welcome to flatland's documentation!
    gettingstarted
    intro_observationbuilder
    specifications/specifications.md
-   localevaluation
    modules
    FAQ
+   localevaluation
    contributing
-   authors
    changelog.md
    flatland_2.0.md
+   authors
+
 
 
 
diff --git a/docs/intro_observationbuilder.rst b/docs/intro_observationbuilder.rst
index fd03e26424378448839c57faa14fe730e68698ff..c94a2ce18e80c9b6fbdf34b824dfc2062374c82d 100644
--- a/docs/intro_observationbuilder.rst
+++ b/docs/intro_observationbuilder.rst
@@ -1,5 +1,5 @@
 =====
-Getting Started with custom observations
+Getting Started with custom observations and custom predictors
 =====
 
 Overview
diff --git a/docs/modules.rst b/docs/modules.rst
deleted file mode 100644
index a644cfc997aa6bead6d9e978cca5b823748271aa..0000000000000000000000000000000000000000
--- a/docs/modules.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-flatland
-========
-
-.. toctree::
-   :maxdepth: 4
-
-   flatland
diff --git a/docs/specifications/specifications.md b/docs/specifications/specifications.md
index 3f08025a83e41c8460ab84cf6175a0b7920cb123..ec680147a4cbb2b9bf2962b7bbabd9d5312aecac 100644
--- a/docs/specifications/specifications.md
+++ b/docs/specifications/specifications.md
@@ -1,7 +1,9 @@
-Flatland Environment Specifications
+Flatland Specs
 ==========================
 
-In a humand-readable language:
+What are **Flatland** specs about?
+---------------------------------
+In a humand-readable language, they provide
 * code base overview (hand-drawn concept)
 * key concepts (generators, envs) and how are they linked
 * link relevant code base
@@ -312,5 +314,22 @@ In case of the root node, the values are [0, 0, 0, 0, distance from agent to tar
 In case the target node is reached, the values are [0, 0, 0, 0, 0].
 
 
+## Predictors
+Predictors make predictions on future agents' moves based on the current state of the environment.
+They are decoupled from observation builders in order to be encapsulate the functionality and to make it re-usable.
+
+For instance, `TreeObsForRailEnv` optionally uses the predicted the predicted trajectories while exploring
+the branches of an agent's future moves to detect future conflicts.
+
+The general call structure is as follows:
+```
+RailEnv.step() 
+               -> ObservationBuilder.get_many() 
+                                                ->  self.predictor.get()
+                                                    self.get()
+                                                    self.get()
+                                                    ...
+```
+
 ## [Rendering](rendering)
 ## [Railway](railway)