Improve accessibility

[imaginator]

Describe the feature

When I'm speaking to potential Simplicity contract developers, I point them to this repo as a way to introduce them to more advanced contracts. I then usually have to also point them to the https://github.com/BlockstreamResearch/simplicity-contracts/tree/main/crates/cli#dcd-commands so that they can understand what's going on.

The general response is "oh man this is complicated" or something along those lines.

IMHO the CLI commands are flow are the best way to understand how the contracts work but hidden away in a directory - and it would be good to expose them more or somehow make the repo a little more accessible.

I don't know the right way to solve this, but did want to report a recurring issue.

[imaginator]

Some other feedback was that the scripts would be more helpful with some code comments.

[KyrylR]

@imaginator I have been thinking about this. Ideally, we would come to the point where devs would naturally start using Simplicity based on others’ examples. Before that, I would take inspiration from: https://doc.rust-lang.org/book/

Also, I believe @schoen is already doing a decent job of steering the docs and website in the right direction

I fully agree that there are missing docs in Simplicity, though I do not want to overload this repo with explanations only for newcomers, since I see it as an actual library

[topologoanatom]

@KyrylR I’ve added a new README section describing the canonical contract structure used in this repository, using array_tr_storage as a concrete example.

The documentation explains, step by step:

• how contract development starts from pure SimplicityHL logic (.simf);
• how this logic is specialized at build/execution times via build_arguments.rs, build_witness.rs;
• how everything is glued together and integrated into the Rust / SDK in mod.rs;

The goal is to give newcomers a clear mental model of:

• where to start when writing a new contract,
• why the repository is structured the way it is,
• and what role each file plays (logic vs build-time params vs witness vs integration).

[KyrylR]

Cool, please create a PR

[KyrylR]

@topologoanatom also before creation a PR please read this: https://github.com/BlockstreamResearch/simplicity-contracts/blob/main/CONTRIBUTING.md

[topologoanatom]

@KyrylR Apart from a more elaborate description of how to implement a new contract, I think it also makes sense to reconsider the repository layout. Moving all parts under the crates folder gives the impression that they are mutually dependent, while in practice this does not seem to be the case. As you mentioned previously, this repository is better understood as a library, with only the contracts crate being published on crates.io. Making this distinction more explicit in the layout could help improve accessibility and reduce confusion for new users.

[KyrylR]

What exactly do you want to change?

[topologoanatom]

Unpack crates folder into root directory entirely or move only contracts, leaving cli and simplicityhl-core together

[KyrylR]

As I mentioned before, I do not what to make it a tutorial repository

Instead I wanna see a collab between the https://simplicity-lang.org/ and this repo