1 files changed, 51 insertions, 0 deletions
diff --git a/doc/source/junctions/junction-workspaces.rst b/doc/source/junctions/junction-workspaces.rst
new file mode 100644
index 000000000..a9176063c
--- /dev/null
+++ b/doc/source/junctions/junction-workspaces.rst
@@ -0,0 +1,51 @@
+
+
+.. _junction_workspaces:
+
+Workspaces and subprojects
+==========================
+When developping a project with :mod:`junctions <elements.junction>` and
+subprojects, you will probably end up needing to work on the subprojects
+as well.
+
+Opening :ref:`workspaces <developing_workspaces>` works mostly in the
+same way as it does with subprojects as it does for elements directly
+in your own project.
+
+.. note::
+
+    This section runs commands on the same example project presented in the
+    :ref:`previous section <junction_elements>`, which is distributed with BuildStream in the
+    `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_
+    subdirectory.
+
+
+Workspacing a junction
+----------------------
+Sometimes you need to work on the elements declared in a subproject
+directly. As the downstream consumer of a junctioned project, it makes
+sense that you might need to work on that project as well in order
+to satisfy the needs of your downstream project.
+
+You can easily work on your subproject by :ref:`opening a workspace <invoking_workspace_open>`
+on the junction element directly.
+
+.. raw:: html
+   :file: ../sessions/junctions-workspace-open-subproject.html
+
+After opening a workspace on the junction element, the open workspace
+is used to define the subproject, allowing you to make changes to
+how the subproject is built, add new dependencies and configure the
+subproject in any way.
+
+
+Cross-junction workspaces
+-------------------------
+You can open workspaces for elements in the project refered to by the junction
+using the syntax ``bst open ${junction-name}:{element-name}``. In this example,
+
+.. raw:: html
+   :file: ../sessions/junctions-workspace-open.html
+
+This has opened a workspace for the hello.bst element from the autotools project.
+This workspace can now be used as normal.