...

We Document all levels of the openIDL network setup and management, starting with the openIDL wiki and migrate to ReadTheDocs when ready. 

...

We document the Infrastructure as Code / Setup of the Network using the Wiki (in the short term)

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 avoid unexpected changes

Considered Options

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

Decision Outcome

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

Consequences

• Good, because the wiki is easy to manage, add, remove, move, edit documentatioindocumentation and versioned
• 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
• Bad due to access issues 

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
• Good/Bad: Versioning can be a challenge
• 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

GitHub

• Good, commonly used
• Good, version control
• Good, docs stay with codebase
• Bad, hard to navigate, raw form
• Bad, manual navigation