Improve Structure for "Integrating Cardano" section
The structure of Integrate Cardano should be improved. Below ere are the issues I found. I aggregate them all here as to not spam the Issues Tab with my own issues. You can create new issues and assign them to me if you like, I'll do them whenever I have some time to spare.
I am not sure how much thought went into this section and I apologize if I miss the advantages of the current structure
Sub issues
No content in Overview
IMHO the integrate-cardano/Overview.md needs to talk about what this section is about.
Inconsistent Headings
The used headings in the articles creating-wallet-faucet.md
, listening-for-payments-cli.md
and listening-for-payments-wallet.md
begin on level 3
instead of level 2
breaking md001
Current
├╌┬ integrate-cardano/
┆ ├╌╌╌ overview.md (slug: integrate-cardano)
├╌┬╌ creating-wallet-faucet.md (title: Exploring Cardano Wallets)
│ ├╌ ### Overview
│ ├╌ ### Cardano Wallets
│ ┆
┆
├╌┬╌ listening-for-payments-cli.md
│ ├╌ ### Overview
│ ├╌ ### Use case
│ ┆
┆
└╌┬╌ listening-for-payments-wallet.md
├╌ ### Overview
├╌ ### Use case
┆
Proposed
├╌┬ integrate-cardano/
┆ ├╌╌╌ overview.md (slug: integrate-cardano)
├╌┬╌ creating-wallet-faucet.md (title: Exploring Cardano Wallets)
│ ├╌ ## Overview
│ ├╌ ## Cardano Wallets
│ ┆
┆
├╌┬╌ listening-for-payments-cli.md
│ ├╌ ## Overview
│ ├╌ ## Use case
│ ┆
┆
└╌┬╌ listening-for-payments-wallet.md
├╌ ## Overview
├╌ ## Use case
┆
The above structure will also improve the side-bar in the guide to contain subchapters and allow to jump to topics like creating a wallet with cardano-cli
.
Throughout the article (f.e. in ### Create simple transaction
paragraphs) we use Emphasis (**Generate recovery phrase**
) instead of Heading (#### Generate recovery phrase
) breaking md036
Long articles
creating-wallet-faucet.md
is a very long article and talks about the following topics:
- Overview
- Carano wallets
- Creating a wallet
- Creating a wallet with
cardano-cli
- Querying the wallet UTXO with
cardano-cli
- Creating simple transaction
- generate payment key-pair for wallet 1
- generate wallet address for wallet 1
- query UTxOs for wallet 1
- requesting funds from Testnet Faucet
- generate payment key-pair for wallet 2
- generate wallet address for wallet 2
- query wallet UTxOs for wallet 2
- query protocol parameters
- Create draft transaction
- Calculate min fee
- Create draft transaction
- Sign transaction
- Submit transaction
- Creating a wallet with
cardano-wallet
- Starting cardano-wallet as a REST API Server
- Checking wallet server information
- Creating the wallet via API
- Receiving tADA (Test ADA)
- Creating simple transaction
- generate recovery phrase
- recovery phrase result
- create wallet request
- create wallet result
The following subissues could help improve readability.
Testnet Faucet Limit
If one works through the entire article he will first submit 1000 ada to the wallet he created using cardano-cli
. Then (20 minutes later) he will create a new wallet using cardano-wallet
and again request 1000 ada from the faucet which has a payout limit for 1000 ada / day.
Oddball solution
We have the focus on two components: cardano-cli
and cardano-wallet
. We try to give the reader an idea on how to integrate them.
We use two approaches to present this information to him. theme-based approach and component-based approach
I think I like Component-based more because the articles are shorter, but I really don't know what is better.
Don't repeat yourself
The guides contain some repetition. Sometimes this is unavoidable when talking about two components who do very similar things. The improvements should help avoid the unneccesary repetitions.
As an example, we have this paragraph from the cardano-wallet-faucet.md
As mentioned before, in this guide we will only be focusing on the cardano-cli and cardano-wallet since they provide some level of programmability which is important when we are talking about Cardano integrations for different kinds of use-cases.
This could be moved to the overview.md
and not be talked about anymore. By removing this paragraph we could move all headings one layer up which would improve the structure of document further.
Typos
Improve current structure (draft)
Until we settle on the approach of the guide (theme-based or component-based or both or leave it as is) I'll leave this here as a draft and "mind map"
### Current structure
┆
├╌┬ integrate-cardano/
┆ ├╌╌╌ overview.md (slug: integrate-cardano)
├╌┬╌ creating-wallet-faucet.md (title: Exploring Cardano Wallets)
│ ├╌ ### Overview
│ ├╌ ### Cardano Wallets
│ ├╌ ### Creating a wallet
│ └┬╌ #### Creating a wallet with `cardano-cli`
│ ├╌ #### Querying the wallet UTxO with `cardano-cli`
│ ├╌ #### Creating simple transactions
│ ├╌ #### Querying the wallet UTxO with `cardano-wallet`
│ └╌ #### Creating simple transactions
├╌┬╌ listening-for-payments-cli.md
│ ├╌ ### Overview
│ ├╌ ### Use case
│ ├╌ ### Technical flow
│ ├╌ ### Time to code!
│ ├╌ ### Running and Testing
│ └╌ ### Complete the payment
└╌┬╌ listening-for-payments-wallet.md
├╌ ### Overview
├╌ ### Use case
├╌ ### Technical flow
├╌ ### Time to code!
├╌ ### Running and Testing
└╌ ### Complete the payment
### Theme Baseed Structure (Proposed)
┆
├╌┬ integrate-cardano/
┆ ├╌╌ overview.md (slug: integrate-cardano)
├╌┬╌ creating-wallet-faucet.md (slug: )
│ ├ ## Overview
│ ├ ## Cardano Wallets
│ ├ ## Creating a wallet
│ ├┬╌ ### Create wallet with `cardano-cli`
│ ├┬╌ ### Create wallet with `cardano-wallet`
│ └╌ Cardano Wallets
├╌
└╌
### Component-Baseed Structure (Proposed)
┆
├╌┬ integrate-cardano/
┆ ├╌╌ overview.md (slug: integrate-cardano)
├╌┬╌ creating-wallet-faucet.md (slug: )
│ ├ ## Overview
│ ├ ## Cardano Wallets
│ ├ ## Create wallet with `cardano-cli`
│ ├╌┬╌ ### Create wallet with `cardano-cli`
│ ├╌┬╌ ### Create wallet with `cardano-wallet`
│ │ └╌ Cardano Wallets
│ ├ ## Create wallet with `cardano-cli`
│ ├╌┬╌ ### Create wallet with `cardano-cli`
│ ├╌┬╌ ### Create wallet with `cardano-wallet`
│ └╌ Cardano Wallets
├╌
└╌