cardano-foundation / developer-portal

The Cardano Developer Portal
https://developers.cardano.org
MIT License
379 stars 911 forks source link

Add structure to `Integrate Cardano` #140

Open tweakch opened 3 years ago

tweakch commented 3 years ago

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:

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
  ├╌
  └╌ 
tweakch commented 3 years ago

And let me say that I really like the portal so far... the you've done a fantastic job @katomm @Mercurial @Nazeim @rcmorano @AndrewWestberg and everyone I forgot...

Mercurial commented 3 years ago

this issue makes me so happy! I will be reviewing this in the next couple days, thank you so much!