From 8cac69d2522ae37b2bb976347b5aad853c04795a Mon Sep 17 00:00:00 2001 From: Mike Hearn Date: Fri, 11 May 2018 17:32:19 +0200 Subject: [PATCH] Docs: re-organise the toctree a bit more and introduce a design section It includes (for now) just the design template. --- docs/source/aws-vm.rst | 6 +++--- docs/source/azure-vm.rst | 4 ++-- docs/source/corda-networks-index.rst | 4 ++-- docs/source/corda-nodes-index.rst | 4 ++-- docs/source/design/README.md | 2 +- ...nReviewProcess.md => design-review-process.md} | 12 ++++++------ docs/source/design/designTemplate/design.md | 2 +- docs/source/index.rst | 15 +++++++++++++-- docs/source/other-index.rst | 9 --------- docs/source/tools-index.rst | 3 --- 10 files changed, 30 insertions(+), 31 deletions(-) rename docs/source/design/{designReviewProcess.md => design-review-process.md} (98%) delete mode 100644 docs/source/other-index.rst diff --git a/docs/source/aws-vm.rst b/docs/source/aws-vm.rst index b0f518480e..571620463c 100644 --- a/docs/source/aws-vm.rst +++ b/docs/source/aws-vm.rst @@ -1,5 +1,5 @@ -Building a Corda VM from the AWS Marketplace -============================================ +AWS Marketplace +=============== To help you design, build and test applications on Corda, called CorDapps, a Corda network AMI can be deployed from the `AWS Marketplace `__. Instructions on running Corda nodes can be found `here `_. @@ -12,7 +12,7 @@ Pre-requisites Deploying a Corda Network ---------------------------- +------------------------- Browse to the `AWS Marketplace `__ and search for Corda. diff --git a/docs/source/azure-vm.rst b/docs/source/azure-vm.rst index e346c24c2b..8661422006 100644 --- a/docs/source/azure-vm.rst +++ b/docs/source/azure-vm.rst @@ -1,5 +1,5 @@ -Building a Corda Network on Azure Marketplace -============================================= +Azure Marketplace +================= To help you design, build and test applications on Corda, called CorDapps, a Corda network can be deployed on the `Microsoft Azure Marketplace `_ diff --git a/docs/source/corda-networks-index.rst b/docs/source/corda-networks-index.rst index 270726948e..cc3e81321e 100644 --- a/docs/source/corda-networks-index.rst +++ b/docs/source/corda-networks-index.rst @@ -1,5 +1,5 @@ -Corda networks -============== +Networks +======== .. toctree:: :maxdepth: 1 diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index 6bf9c361b9..da92cdf876 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -1,5 +1,5 @@ -Corda nodes -=========== +Nodes +===== .. toctree:: :maxdepth: 1 diff --git a/docs/source/design/README.md b/docs/source/design/README.md index 94161e68bc..64e212f3f7 100644 --- a/docs/source/design/README.md +++ b/docs/source/design/README.md @@ -10,7 +10,7 @@ These should be written in [Markdown](https://github.com/adam-p/markdown-here/wi ## Design Review Process -Please see the [design review process](./designReviewProcess.md). +Please see the [design review process](design-review-process.md). * Feature request submission * High level design diff --git a/docs/source/design/designReviewProcess.md b/docs/source/design/design-review-process.md similarity index 98% rename from docs/source/design/designReviewProcess.md rename to docs/source/design/design-review-process.md index 57cc17b5b3..c5c658d6b4 100644 --- a/docs/source/design/designReviewProcess.md +++ b/docs/source/design/design-review-process.md @@ -1,9 +1,8 @@ - -# Overview +# Design review process The Corda Design Review process defines a means of editing, storing, collaborating, reviewing and approving Corda documentation in a consistent, structured, easily accessible and open manner. -# Background +## Background Historically, Corda design documentation has been produced in an ad hoc fashion to include: * Multiple sources and formats of storage @@ -20,7 +19,7 @@ Historically, Corda design documentation has been produced in an ad hoc fashion * Lack of proposed implementation plan (time, resources, effort). * Often missing stakeholder collaboration and review in the feedback cycle. -# Process +## Process This process specifies: @@ -53,7 +52,8 @@ The following diagram illustrates the process flow: ![Design Review Process](./designReviewProcess.png) -# Review Groups +## Review Groups + Design documents should include all relevant stakeholders in their distribution (mostly as PR reviewers in github). This will often vary and depend on the origin of the Feature Request, particularly for high level business requirements. Technical Design Documents will tend to include a small set of stakeholders (Design Approval Board, Platform Development, DevOps). Final approval authority lays with at least one member of the Design Approval Board (DAB) or nominated delegate(s). Design Approval Board (DAB) @@ -91,7 +91,7 @@ Other review groups inlcude: * Customers * Key collaborators -# Applicability and Timing +## Applicability and Timing This process should be applied to any major feature request gathered by the product management team or lead technologists that has been entered in the product backlog as a requirement, and has been prioritized for imminent execution. diff --git a/docs/source/design/designTemplate/design.md b/docs/source/design/designTemplate/design.md index 37c8ed3660..601e2f7074 100644 --- a/docs/source/design/designTemplate/design.md +++ b/docs/source/design/designTemplate/design.md @@ -2,7 +2,7 @@ # Design Template -Please read the [Design Review Process](../designReviewProcess.md) before completing a design. +Please read the [Design Review Process](../design-review-process.md) before completing a design. This design template should be used for capturing new Corda feature requests that have been raised as JIRA requirements stories by the product management team. The design may be completed in two stages depending on the complexity and scope of the new feature. diff --git a/docs/source/index.rst b/docs/source/index.rst index 05499f86f9..44694f4e09 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,7 +30,7 @@ We look forward to seeing what you can do with Corda! .. _`download the PDF`: _static/corda-developer-site.pdf .. toctree:: - :caption: App development + :caption: Development :maxdepth: 1 quickstart-index.rst @@ -48,10 +48,21 @@ We look forward to seeing what you can do with Corda! corda-nodes-index.rst corda-networks-index.rst + azure-vm.rst + aws-vm.rst + loadtesting.rst + +.. toctree:: + :caption: Design docs + :maxdepth: 2 + + design/design-review-process.md .. toctree:: :caption: Participate :maxdepth: 2 release-process-index.rst - other-index.rst + corda-repo-layout.rst + building-the-docs.rst + json.rst diff --git a/docs/source/other-index.rst b/docs/source/other-index.rst deleted file mode 100644 index f6d60548e7..0000000000 --- a/docs/source/other-index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Other -===== - -.. toctree:: - :maxdepth: 1 - - corda-repo-layout - building-the-docs - json diff --git a/docs/source/tools-index.rst b/docs/source/tools-index.rst index 3955a0cbe1..55b398dd35 100644 --- a/docs/source/tools-index.rst +++ b/docs/source/tools-index.rst @@ -7,6 +7,3 @@ Tools network-simulator demobench node-explorer - azure-vm - aws-vm - loadtesting \ No newline at end of file