search

hyperledger / cacti

Hyperledger Cacti is a new approach to the blockchain interoperability problem
https://wiki.hyperledger.org/display/cactus
Apache License 2.0
326 stars 276 forks source link

docs(examples): cover different levels of immersion #862

Open petermetz opened 3 years ago

petermetz commented 3 years ago

Description

As a developer thinking of using Cactus on a project I want to have step by step tutorials walking me different levels of immersion of the framework so that I can untangle what's mandatory and what's optional within the framework.

Why? Because right now if you read the code of the supply chain app for example, you see an entire project there, complete with a REST API, a front end application, etc. so it might be difficult to figure out what is Cactus in that whole stack and what's just things that we added so that we can have a complete example.

Acceptance Criteria

  1. Include a layered technology stack diagram demonstrating what's Cactus and what isn't
  2. Cover in a step by step tutorial a scenario where someone has their project set up already and all they want is to use one of the connectors as a dependency (lowest level of immersion)
  3. Cover in a step by step tutorial a scenario where someone has a project already, but maybe it's not a NodeJS project so they don't just need an npm dependency, but they want the Cactus API server load up with connector plugins + keychain + authz + containerization
  4. Cover in a step by step tutorial the fully immersive example where someone wants to leverage all the bells and whistles the framework provides which would mean that they implement a business logic plugin to host the front end and to host their API endpoints and then load all that up to the API server and that's their entire technology stack, through Cactus (this is basically what the supply chain app and the carbon accounting app examples show, and we are missing the other 3 points from above which means it's probably easy for people to get overwhelmed by these mentioned examples because they are the most comprehensive ones, e.g. we throw people in the deep water right off the bad if we just link to those examples as a point of getting started)

cc: @takeutak @sfuji822 @hartm @jonathan-m-hamilton @AzaharaC @jordigiam @kikoncuo @jagpreetsinghsasan @arnab-roy

sfuji822 commented 3 years ago

I agree with the issue, but it is for example? I thought that is more appropriate to raise the issue on docs(whitepaper) for changing its structure. @petermetz

petermetz commented 3 years ago

@sfuji822 We could have a version of it in the whitepaper too IMO. In the scope of this issue I just wanted the read the docs site to have a dedicated page on it that's accessible through the side menu on the left hand side and the actual code examples should be provided (the latter could overkill for the whitepaper)