Use consistent paths in code samples (accross all guides)

[tweakch]

It would make sense to agree on a consistent environment across guides

From what I've seen so far, it's pretty consistent but not everywhere... I find that I have to switch directory structure between different guides and my files started ending up everywhere...

I would suggest the following setup

/home/user/cardano
|_ /keys # from cardano-cli guides
|_ /wallets # from cardano-wallet guides
|_ /db
|_ /integrate-cardano-samples
  |_ /id-of-guide-1
    |_ draft.tx
    |_ draft.signed
  |_ /id-of-guide-2
  |_ ...
|_ /build-tx-metadata-samples
  |_ /id-of-guide-1
  |_ /id-of-guide-2
  |_ ...

This setup would allow all guides to first ask the user to check that he is in the correct directory (and let him cd into it)

$ pwd
/home/user/cardano/integrate-cardano-samples

and then for cardano-cli commands "reach up" for .skeys or protocol.json

$ cardano-cli query utxo \
--testnet-magic 1097911063 \
--address $(cat ../keys/payment1.addr)

cardano-cli transaction sign \
--tx-body-file tx.draft \
--signing-key-file ../keys/payment1.skey \
--testnet-magic 1097911063 \
--out-file tx.signed

[tweakch]

I think there should be a Setup environment page that guides can reference and explains the rational behind the structure...

[katomm]

You are providing outstanding contributions here. I love the idea of doing a pwd before guides.

Regarding directories, I am a little hesitant although I agree with you completely. For example, the "build with transaction metadata" was named "transaction metadata" in the beginning. Then later renamed for better user experience/SEO/marketing reasons. I'm afraid that might happen again and we'll always have to redirect the links.

[tweakch]

Thank you I believe this portal is one of the most important things for driving adoption and I'm happy to help.

I can totally see why this is difficult to maintain.

Maybe we could embed everything in some kind of a curriculum with a number system that can be extended and has a logic to it.

Like courses in university.

Then users could cd into <courseId> and work from there.

I'm makong this up as I go... 😅

[tweakch]

As I re-read your comment I noticed a possible misunderstanding:

I'm afraid that might happen again and we'll always have to redirect the links.

Are you talking about the file structure on the server? I'm talking about the local workspace. and the paths used in the guides. I am also much more hesitant to change the structure on the server and re-link the entire guides all the time. Let me explain why I raised this issue:

When people work through the guides, they are asked to

mkdir -p /home/user/cardano/keys

Some devs will already have a folder ~/cardano with tons of stuff in there, but ok. They finish the guide and hopefully learned a lot. Then in the next guide we ask them to

mkdir -p /home/user/receive-ada-sample/keys

Can't they use ~/cardano/keys from the last guide? Why not mkdir -p ~/cardano/receive-ada-sample and use ../keys/... in the commands? Obviously they can and most of them will. I just think it's a little clumsy, thats all.

A lot of devs will rely on these guides while trying to wrap their heads around transactions and wallets and metadata and I think it's unfair to make it harder for them than it is. That said, people have brains and will figure out a system that works for them.

[rdlrt]

Just a point of reference (I agree with what you raise), while this folder structure in this doco should possibly only be present for guide presented here and be consistent, it is already different/unique than any other guides (for example, for guild-ops, wherein there is very different folder structure intentionally kept outside of home folder).

It wouldn't matter much to other guides ofcourse, but just thinking about aligning where possible the structure below top-level folder. To expand on one of the lines above, keys for wallet and CLI, can be used interchangeably (there are ways to derive keys using CLI for specific wallet address scheme), while keys for node/pool are seperate to wallet. As such, the example of keys, wallets under top level already can be conceptually different understanding

[katomm]

@tweakch you are right, at first I thought you were talking about the file structure of the docs as well.

[tweakch]

@rdlrt Very important point... the guides need to contain best practices from the community.

I must admit I'm out of my depth pretty quickly when it comes to those issues so I wouldn't want to design these environments. I'm a developer and follow what my sysadmin tells me to do.

That said, I'm very much willing to learn and try the developer-portal guides with the guild-ops setup and share my findings so we can update the guides accordingly...

[tweakch]

Just a thought... Maybe a docusaurus plugin could support us be consistent.

docs plugin already reports broken markdown links here

We could write our own... quick and dirty one. Am I overthinking it? 🤣