search

smartcontractkit / chainlink-local

The Chainlink CCIP Local Simulator, visit documentation by clicking the link below:
https://docs.chain.link/chainlink-local
MIT License
50 stars 15 forks source link

Zp/ga review2 #3

Closed zeuslawyer closed 6 months ago

zeuslawyer commented 6 months ago

Streamline docs for improved readability.

Replace code snippets with references to code in repo to avoid duplication of snippets (reduce maintenance risk).

andrejrakic commented 6 months ago

Why would we want to remove the minimal code snippet needed to get started with the tool, both from the README and DOCUMENTATION?

The replaced code snippets are generic and let anyone quickly get started with the chainlink-local. By removing them, devs wouldn't know how to do the "chainlink-local's hello world thing" easily.

We already have URLs at the bottom of the DOCUMENTATION that showcase more advanced features, there is no need to remove the "getting started" code snippets.

Now both docs and readme look much less readable to me.

zeuslawyer commented 6 months ago

Hey Andrej I can see why it appears that way! some background:

re updates to DOCUMENTATION, I wasnt able to follow along using what was there.

I made updates to the README as I followed along. Once I added the snippets, i had to figure out how to use it in a project of my own etc... so not a "quick start" as it leads to a dead end unless I already had an active project.

Most developers will explore before they adopt. To explore, the snippets dont take the developer the whole way.

So I had to look at your video and then find code similar to it in the repo before i could reproduce your outcomes from the video. The README alone was not enough to complete exploration. The snippets only show the setup() function and not the operational test code.

After I got it to work, I adjusted the README and DOCUMENTATION to point to the resources necessary to have a working example running. So The updates reflected the steps I needed to follow to get it to work as per your video (and i had the advantage of having a video, otherwise it would have taken significantly longer to work my way through it - not a quick start)

So...I feel pointing to the resources directly is also faster for a quick start as it gives devs a fully working example as opposed to just the initialization. Full working examples are faster to understand and reason through to see how to use something.

Also linking to the canonical code file is DRY and reduces risk of the code and snippets being out of sync over time.

With respect to the README, if those changes read sensibly, please consider updating the README for those.