Re-organise a part of the versioning discussion into a new toctree section.

docs/source/building-a-cordapp-index.rst

@@ -12,10 +12,6 @@ CorDapps
    cordapp-build-systems
    building-against-master
    debugging-a-cordapp
-   versioning
-   upgrading-cordapps
-   cordapp-constraint-migration
-   cordapp-upgradeability
    secure-coding-guidelines
    flow-overriding
    flow-cookbook

docs/source/corda-api.rst

@@ -1,27 +1,3 @@
-Corda API
-=========
-
-The following are the core APIs that are used in the development of CorDapps:
-
-.. toctree::
-   :maxdepth: 1
-
-   api-states
-   api-persistence
-   api-contracts
-   api-contract-constraints
-   api-vault-query
-   api-transactions
-   api-flows
-   api-identity
-   api-service-hub
-   api-service-classes
-   api-rpc
-   api-core-types
-   api-testing
-
-Before reading this page, you should be familiar with the :doc:`key concepts of Corda <key-concepts>`.
-
 .. _internal-apis-and-stability-guarantees:
 
 API stability guarantees

docs/source/versioning-and-upgrades.rst

@@ -0,0 +1,24 @@
+Versioning and upgrades
+=======================
+
+| *Change is inevitable, except from a vending machine*
+| -- Abraham Lincoln
+|
+
+This section of the guide covers how CorDapps are versioned and how to manage upgrades in a decentralised network. It should be read when
+you're at a stage of your development that requires planning for post-launch iteration. You will learn:
+
+* How the ledger expresses to what extent business logic can be changed and by who.
+* How change is managed in a world where there are no privileged administrators who can force upgrades.
+
+It's worth planning for versioning and upgrades from the start, especially if you plan for your CorDapp to itself provide APIs to other
+apps. Apps extending the platform with industry-specific data models is a common case, and ensuring you can evolve your data model as
+the world changes is a key part of any professionally built software.
+
+.. toctree::
+   :maxdepth: 1
+
+   versioning
+   upgrading-cordapps
+   cordapp-constraint-migration
+   cordapp-upgradeability