Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

We Document all levels of the openIDL network.


...

We document the Infrastructure as Code / Setup of the Network using the Wiki

Context and Problem Statement

The openIDL network is a complex network of nodes connected using the Hyperledger Fabric Distributed Ledger Technology.

...

  • Cloud infrastructure - whether in AWS, Azure, GCP or some other, this is the set of virtual machines and networking necessary to run the software.
  • Hyper Ledger Fabric - this is the kubernetes assets that support the DLT.  This also includes the management console.
  • Application - this is the application code that supports the business cases such as stat reporting or data calls.

Decision Drivers

  • The different levels of setup are automated as much as possible.

  • The documentation must guide a potential participant through all steps

  • The documentation must be available to the public

  • The documentation must be governed enough to keep unexpected changes

Considered Options

  • Linux Foundation wiki - wiki.openIDL.org
  • Microsoft Word
  • Google Docs
  • Read the Docs
  • Video / Screen Capture tutorials

Decision Outcome

  • For the time being, the documentation is captured in this wiki.
  • As it matures alternatives may be considered for different aspects.

Consequences

  • Good, because the wiki is easy to manage, add, remove, move, edit documentatioin
  • Good, because the wiki is open to all
  • Good, because the wiki can be permissioned
  • Bad, because  wiki's can become disorganized

Pros and Cons of the Options

Linux Foundation Wiki - wiki.openidl.org

  • Good, because easy to manage
  • Good, because open to all 
  • Bad, because wiki's can become disorganized

Microsoft Word

  • Good, because it is well known
  • Good, because it is easy to use
  • Good, because it is easy to create professional format
  • Good, because diagrams etc are easy to include
  • Bad, because it is document oriented and leads to complicated merging
  • Bad, because it is sometimes hard to know which version
  • Bad, because extra step to pen the document.

Google Docs

  • Good, because it is well known
  • Good, because it is easy to use
  • Good, because diagrams etc are easy to include
  • Good, because although it is document oriented it is easy to work together
  • Neutral, because it is easy to create professional format
  • Bad, because doesn't fit the wiki well for inclusion

Read the Docs

  • Good, because it is used by HLF
  • Good, because it is easy to access and navigate
  • Good, because it is built on github and is inherently versioned
  • Good, because it is built for version control and team development
  • Bad, because diagrams etc are difficult to include
  • Bad, because maintenance requires extra steps
  • Bad, because raw format is markdown and not easy to read

Videos / Screen Captured Tutorials

  • Good, because they provide effective information
  • Good, because they are easy to use
  • Bad, because they are difficult to keep up to date

...