diff --git a/doc/dev/setup.rst b/doc/dev/setup.rst
new file mode 100644
index 000000000..4083a3da8
--- /dev/null
+++ b/doc/dev/setup.rst
@@ -0,0 +1,50 @@
+Development Setup
+=================
+
+Setup development environment
+-----------------------------
+
+.. note::
+
+ If you have already installed Edalize, remove it first using ``pip3 uninstall edalize``.
+
+To develop Edalize and test the changes, the edalize package needs to be installed in editable or development mode.
+In this mode, the ``edalize`` command is linked to the source directory, and changes made to the source code are
+immediately visible when calling ``edalize``.
+
+.. code-block:: bash
+
+ # Install all Python packages required to develop edalize
+ pip3 install --user -r dev-requirements.txt
+
+ # Install Git pre-commit hooks, e.g. for the code formatter and lint tools
+ pre-commit install
+
+ # Install the edalize package in editable mode
+ pip3 install --user -e .
+
+.. note::
+
+ All commands above use Python 3 and install software only for the current user.
+ If, after this installation, the ``edalize`` command cannot be found adjust your ``PATH`` environment variable to
+ include ``~/.local/bin``.
+
+After this installation is completed, you can
+
+* edit files in the source directory and re-run ``edalize`` to immediately see the changes,
+* run the unit tests as outlined in the section below, and
+* use linter and automated code formatters.
+
+Formatting and linting code
+---------------------------
+
+The Edalize code comes with tooling to automatically format code to conform to our expectations.
+These tools are installed and called through a tool called `pre-commit `_.
+No setup is required: whenever you do a ``git commit``, the necessary tools are called and your code is automatically formatted and checked for common mistakes.
+
+To check the whole source code ``pre-commit`` can be run directly:
+
+.. code-block:: bash
+
+ # check and fix all files
+ pre-commit run -a
diff --git a/doc/source/tests.rst b/doc/dev/tests.rst
similarity index 100%
rename from doc/source/tests.rst
rename to doc/dev/tests.rst
diff --git a/doc/source/edalize.rst b/doc/edalize.rst
similarity index 100%
rename from doc/source/edalize.rst
rename to doc/edalize.rst
diff --git a/doc/genindex.rst b/doc/genindex.rst
new file mode 100644
index 000000000..d4fc2f48f
--- /dev/null
+++ b/doc/genindex.rst
@@ -0,0 +1,4 @@
+.. # This file is a placeholder and will be replaced
+
+Index
+#####
diff --git a/doc/index.rst b/doc/index.rst
index fa501d522..4ca892032 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -18,19 +18,26 @@
Welcome to Edalize's documentation!
===================================
+Edalize is a Python Library for interacting with EDA tools.
+It can create project files for supported tools and run them in batch or GUI mode (where supported).
+
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ :caption: Reference
+ :hidden:
edam/api
- source/modules
- source/tests
+ Modules
+.. toctree::
+ :caption: Developer's Guide
+ :hidden:
-Indices and tables
-==================
+ dev/setup
+ dev/tests
+.. toctree::
+ :caption: Indices and tables
+ :hidden:
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+ genindex
+ Module Index
diff --git a/doc/py-modindex.rst b/doc/py-modindex.rst
new file mode 100644
index 000000000..5f07d3e25
--- /dev/null
+++ b/doc/py-modindex.rst
@@ -0,0 +1,4 @@
+.. # This file is a placeholder and will be replaced
+
+Search Page
+###########
diff --git a/doc/source/modules.rst b/doc/source/modules.rst
deleted file mode 100644
index 9908a3228..000000000
--- a/doc/source/modules.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-Modules
-=======
-
-.. toctree::
- :maxdepth: 4
-
- edalize
diff --git a/tests/README.rst b/tests/README.rst
index d9e452949..c166e6391 100644
--- a/tests/README.rst
+++ b/tests/README.rst
@@ -1,17 +1,11 @@
-***************
Testing edalize
-***************
-
-Users
-=====
+###############
To run the tests, call :command:`pytest`.
-Developers
-==========
Mocks for commands
-------------------
+==================
We provide mocks (stand-ins) for all tools that we want to exercise in tests (located in :file:`tests/mock_commands/`).
These mocks are very simplified "models" of the actual tool, and are called instead of the actual tool.
@@ -25,8 +19,9 @@ In a more complex test setup (e.g. for ``vcs``),
* we make the file executable
* we set the access and modified times of generated files to the current time
+
Testcases
----------
+=========
To define a testcase, use the :func:`edalize_common.make_edalize_test` pytest factory fixture.
This defines a factory that you can call to set up a mocked-up backend appropriately.