...
We
...
parent: Decisions nav_order: 100 title: ADR Template
These are optional elements. Feel free to remove any of them.
status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-0005}
date: {YYYY-MM-DD when the decision was last updated}
deciders: {list everyone involved in the decision}
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
{short title of solved problem and solution}
Context and Problem Statement
{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
Decision Drivers
- easy to access
- easy to manage
- governed
- formatting
- templatable
Considered Options
- read the docs
- word / excel
- scripts
- wiki
- …
Decision Outcome
Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
Consequences
- Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
- Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
- …
Validation
{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
Pros and Cons of the Options
{title of option 1}
{example | description | pointer to more information | …}
- Good, because {argument a}
- Good, because {argument b}
- Neutral, because {argument c}
- Bad, because {argument d}
- …
{title of other option}
{example | description | pointer to more information | …}
- Good, because {argument a}
- Good, because {argument b}
- Neutral, because {argument c}
- Bad, because {argument d}
- …
More Information
...
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.
On top of the HLF, the nodes require application code to interact with ledger.
There are three layers of the architecture:
- 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 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, documentation will be migrated to ReadTheDocs
Consequences
- Good, because the wiki is easy to manage, add, remove, move, edit documentation 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