Docs: improve organisation of the networks section.

docs/source/compatibility-zones.rst

@@ -4,12 +4,15 @@
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/codesets.js"></script>
 
-Connecting to a compatibility zone
+Compatibility zones
-==================================
+===================
 
-Every Corda node is part of a network (also called a zone) that is *permissioned*. Production deployments require a
+Every Corda node is part of a "zone" (also sometimes called a Corda network) that is *permissioned*. Production
-secure certificate authority. Most users will join an existing network such as the main Corda network or the Corda
+deployments require a secure certificate authority. Most users will join an existing network such as the main Corda
-TestNet.
+network or the Corda TestNet. We use the term "zone" to refer to a set of technically compatible nodes reachable
+over a TCP/IP network like the internet. The word "network" is used in Corda but can be ambiguous with the concept
+of a "business network", which is usually more like a membership list or subset of nodes in a zone that have agreed
+to trade with each other.
 
 To connect to a compatibility zone you need to register with its certificate signing authority (doorman) by submitting
 a certificate signing request (CSR) to obtain a valid identity for the zone. You could do this out of band, for instance

docs/source/corda-networks-index.rst

@@ -4,13 +4,12 @@ Networks
 .. toctree::
    :maxdepth: 1
 
-   joining-a-network
+   compatibility-zones
-   corda-test-networks
+   corda-testnet-intro
    running-a-notary
    permissioning
    network-map
    versioning
-   corda-testnet-intro
    azure-vm-explore
    aws-vm-explore
    gcp-vm

docs/source/corda-test-networks.rst

@@ -1,77 +0,0 @@
-.. _log4j2: http://logging.apache.org/log4j/2.x/
-
-Corda networks
-==============
-
-A Corda network consists of a number of machines running nodes. These nodes communicate using persistent protocols in
-order to create and validate transactions.
-
-There are three broader categories of functionality one such node may have. These pieces of functionality are provided
-as services, and one node may run several of them.
-
-* Notary: Nodes running a notary service witness state spends and have the final say in whether a transaction is a
-  double-spend or not
-* Oracle: Network services that link the ledger to the outside world by providing facts that affect the validity of
-  transactions
-* Regular node: All nodes have a vault and may start protocols communicating with other nodes, notaries and oracles and
-  evolve their private ledger
-
-Bootstrap your own test network
--------------------------------
-
-Certificates
-~~~~~~~~~~~~
-
-Every node in a given Corda network must have an identity certificate signed by the network's root CA. See
-:doc:`permissioning` for more information.
-
-Configuration
-~~~~~~~~~~~~~
-
-A node can be configured by adding/editing ``node.conf`` in the node's directory. For details see :doc:`corda-configuration-file`.
-
-An example configuration:
-
-.. literalinclude:: example-code/src/main/resources/example-node.conf
-:language: cfg
-
-      The most important fields regarding network configuration are:
-
-      * ``p2pAddress``: This specifies a host and port to which Artemis will bind for messaging with other nodes. Note that the
-  address bound will **NOT** be ``my-corda-node``, but rather ``::`` (all addresses on all network interfaces). The hostname specified
-  is the hostname *that must be externally resolvable by other nodes in the network*. In the above configuration this is the
-  resolvable name of a machine in a VPN.
-* ``rpcAddress``: The address to which Artemis will bind for RPC calls.
-* ``webAddress``: The address the webserver should bind. Note that the port must be distinct from that of ``p2pAddress`` and ``rpcAddress`` if they are on the same machine.
-
-Starting the nodes
-~~~~~~~~~~~~~~~~~~
-
-You will first need to create the local network by bootstrapping it with the bootstrapper. Details of how to do that
-can be found in :doc:`network-bootstrapper`.
-
-Once that's done you may now start the nodes in any order. You should see a banner, some log lines and eventually
-``Node started up and registered``, indicating that the node is fully started.
-
-.. TODO: Add a better way of polling for startup. A programmatic way of determining whether a node is up is to check whether it's ``webAddress`` is bound.
-
-In terms of process management there is no prescribed method. You may start the jars by hand or perhaps use systemd and friends.
-
-Logging
-~~~~~~~
-
-Only a handful of important lines are printed to the console. For
-details/diagnosing problems check the logs.
-
-Logging is standard log4j2_ and may be configured accordingly. Logs
-are by default redirected to files in ``NODE_DIRECTORY/logs/``.
-
-Connecting to the nodes
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Once a node has started up successfully you may connect to it as a client to initiate protocols/query state etc.
-Depending on your network setup you may need to tunnel to do this remotely.
-
-See the :doc:`tutorial-clientrpc-api` on how to establish an RPC link.
-
-Sidenote: A client is always associated with a single node with a single identity, which only sees their part of the ledger.

docs/source/corda-testnet-intro.rst

@@ -22,7 +22,7 @@ Click on "Join the Corda Testnet".
 
 Select whether you want to register a company or as an individual on the Testnet.
 
-This will create you an account with the Testnet onboarding application which will enable you to provision and manage multiple Corda nodes on Testnet. You will log in to this account to view and manage you Corda Testnet identitiy certificates.
+This will create an account with the Testnet on-boarding application which will enable you to provision and manage multiple Corda nodes on Testnet. You will log in to this account to view and manage you Corda Testnet identity certificates.
 
 .. image:: resources/testnet-account-type.png 
 
@@ -30,23 +30,17 @@ Fill in the form with your details.
 
 .. note::
 
-   Testnet is currently invitation only. If your request is approved you will receive an email. Please fill in as many details as possible as it helps us proritise requests. The approval process will take place daily by a member of the r3 operations team reviewing all invite requests and making a decision based on current rate of onboarding of new customers.
+   Testnet is currently invitation only. If your request is approved you will receive an email. Please fill in as many details as possible as it helps us prioritise requests. The approval process will take place daily by a member of the r3 operations team reviewing all invite requests and making a decision based on current rate of onboarding of new customers.
 
 .. image:: resources/testnet-form.png 
 
-.. note::
-
-   We currently only support federated login using Google email accounts. Please ensure the email you use to register is a Gmail account or is set up as a Google account and that you use this email to log in.
-
-Gmail is recommended. If you want to use a non-Gmail account you can enable your email for Google: https://support.google.com/accounts/answer/176347?hl=en
-	   
 Once you have been approved, navigate to https://testnet.corda.network and click on "I have an invitation".
 
-Sign in using the Google login service:
+Sign in using either your email address and password, or "Sign in with Google":
 
 .. image:: resources/testnet-signin.png 
 
-When prompted approve the Testnet application:
+If using Google accounts, approve the Testnet application when prompted:
 
 .. image:: resources/testnet-signin-auth.png 
 
@@ -66,7 +60,7 @@ Select the cloud provider you wish to use for documentation on how to specifical
 
 Once your cloud instance is set up you can install and run your Testnet pre-provisioned Corda node by clicking on "Copy" and pasting the one time link into your remote cloud terminal.
 	   
-The installation script will download the Corda binaries as well as your PKI certificates, private keys and suporting files and will install and run Corda on your fresh cloud VM. Your node will register itself with the Corda Testnet when it first runs and be added to the global network map and be visible to counterparties after approximately 5 minutes. 
+The installation script will download the Corda binaries as well as your PKI certificates, private keys and supporting files and will install and run Corda on your fresh cloud VM. Your node will register itself with the Corda Testnet when it first runs and be added to the global network map and be visible to counterparties after approximately 5 minutes.
 
 Hosting a Corda node locally is possible but will require manually configuring firewall and port forwarding on your local router. If you want this option then click on the "Download" button to download a Zip file with a pre-configured Corda node.
 
@@ -76,5 +70,5 @@ Hosting a Corda node locally is possible but will require manually configuring f
 A note on identities on Corda Testnet
 -------------------------------------
 
-Unlike the main Corda Network, which is designed for verified real world identities, The Corda Testnet automatically assigns a "distinguished name" as your identity on the network. This is to prevent name abuse such as the use of offensive language in the names or name squatting. This allows the provision of a node to be automatic and instantaneous. It also enables the same user to safely generate many nodes without accidental name conflicts. If you require a human readable name then please contact support and a partial organsation name can be approved. 
+Unlike the main Corda Network, which is designed for verified real world identities, The Corda Testnet automatically assigns a "distinguished name" as your identity on the network. This is to prevent name abuse such as the use of offensive language in the names or name squatting. This allows the provision of a node to be automatic and instantaneous. It also enables the same user to safely generate many nodes without accidental name conflicts. If you require a human readable name then please contact support and a partial organisation name can be approved.