Add back tutorials using stellar/quickstart

[leighmcculloch]

It looks like at some point we've lost tutorials and instructions for how to use quickstart in the main soroban docs. We used to at an early point in the getting started guide help folks run their contracts on their own private network using the stellar/quickstart image.

What I see today is no mention of it, instead only using testnet:

Ref: https://soroban.stellar.org/docs/getting-started/deploy-to-testnet

I think really early on in the developer journey we need to expose them to quickstart. It ideally should be step 3 in this flow. Quickstart is faster to develop against, albeit with some additional setup cost.

We should definitely promote testnet at the same points to and let folks hitup testnet directly. But still include quickstart as the recommended place to test and run contracts.

[ElliotFriend]

I think really early on in the developer journey we need to expose them to quickstart. ... Quickstart is faster to develop against, albeit with some additional setup cost.

Can you expand on this? How is it faster to develop against? What are the benefits of having an early exposure to the quickstart workflow?

I know quickstart is a really quick (pun intended lol) thing to spin up, but in my experience it's been faster/easier just to use the Futurenet/Testnet environments that are already created/setup/maintained. The rpc and friendbot urls are pretty straight-forward and easy to remember, I don't have to wait (admittedly, a very short time) for the container to spin up. I'm not very well-versed with docker, so there's a whole skillset I don't need to feel incompetent about hehe. Plus, from playing with "classic" Stellar early on in my dev journey, Testnet was the only method I knew about (although I'm sure quickstart was a thing then) to develop on.

My own experience is probably far from a "good baseline" to make decisions off of, just want to better understand what I'm missing.

[ElliotFriend]

I nearly forgot. Some of the quickstart-releated instructions do still exist here: https://soroban.stellar.org/docs/reference/rpc#run-your-own-instance-for-development

Of course, that doesn't address your point about exposing developers to quickstart early on. But, at least the content is still around

[leighmcculloch]

We want quickstart to be known, visible early on so folks reach for it when it is right for them. This could be through the getting started section having a "Run on a Local Network" page, similar to the "Run on Testnet" page we have now. We used to have something like that run on a local network before.

Once developers start going, quickstart serves a variety of purposes better than testnet does:

• You get 1 second ledger closes, so it is faster to dev against, faster for CI.
• It'll soon support a variety of "limit" configurations, so you can develop with unlimited limits, then tune your contract to fit it into pubnet/testnet limits.
• No impact from testnet resets.
• Can run reproducible test runs with a blank slate.
• No impact from testnet congestion.

We see reports from folks who are impacted by testnet resets, etc because they built their dev flow around testnet.

Folks can still use testnet, but exposure to quickstart early means devs that it "speaks to" will know about it upfront, and be able to adopt it when needed later.

[ElliotFriend]

Those are all some really good points. I think it makes sense having it early on in the process for those who will recognize they need it at some point (even if that point is in the future).

What if we changed the "Deploy to Testnet" step to simply "Deploy a Contract"? Then, we could have both the quickstart instructions and the Testnet instructions next to each other, and have some room to explain "here's why you might need the quickstart..." and "here's why you might want to use testnet..."

[leighmcculloch]

Sounds like something to experiment with. If we make the tutorial a dual tutorial for parallel things there's some risk it'll be difficult for the reader to follow. If we stack one tutorial on-top of the other there's some risk that the buried content will be not be discoverable. Maybe there's another way we could present it with inline tabbed code snippets. I defer to what you folks (cc @briwylde08) think is best.

[ElliotFriend]

Ooh, I like the idea of making it tabbed... That might be just right. Experimenting a bit sounds like a good step, though.

[qsctr]

Hi, I was following the tutorials which said to test contracts with soroban contract invoke --wasm ... (e.g. here and here) but my soroban CLI didn't accept that option. After some digging around it seems like it got removed recently (stellar/soroban-tools#997) in the latest release. Is this quickstart docker image supposed to be the replacement for that, and is this issue tracking updating those parts of the docs as well?

[leighmcculloch]

Is this quickstart docker image supposed to be the replacement for that

Yup. The quickstart image provides the same capabilities and more that the original invoke command you're referencing did. So no capability should be lost, but the docs have fallen behind the released tool.

[chadoh]

I discussed this with @tyvdh in the weeks leading up to Meridian, and I think we both preferred moving this to Reference. I moved it in https://github.com/stellar/soroban-docs/pull/504.

The goal is to use Divio's documentation system, with the "Getting Started" section as a quick end-to-end Tutorial tour of Soroban's highlights. I think stopping to have people install and run Docker seems like an unnecessary step in that process.

I personally avoid Docker when at all possible, and I don't think I'm alone. From my experience at NEAR, it seems like the vast majority of people prefer to build against Testnet, rather than figure out how to run their own node. But NEAR also pushes people in that direction, and doesn't have a nice quickstart like Soroban's.

Could this be improved with better tooling? Probably. Are we there yet? I don't think so. Maybe once we have a soroban network start command (in progress!), but if it just runs Docker behind-the-scenes then you'd still need to install & start Docker. If it ran quick built-for-your-hardware binaries instead of Docker containers? Definitely; I'd love that so much. I'd way rather build locally against something like that than against Testnet. But I'd way rather build against Testnet than Docker.

Another benefit of building against Testnet: other people can interact with your app! It's just a web page. They don't need to be a developer and run everything locally. So even if we had super quick Docker-free local dev environments, a lot of people still might prefer building against Testnet. I would, for many kinds of projects.

For now, I think it makes sense to add a section at the top of 2. Deploy to Testnet that explains that you can run your own network locally, that it's easy if you're already comfortable with Docker, and explains the benefits mentioned above (I actually hadn't known these until I read this Issue; thanks @leighmcculloch!). Then links to the Run your own RPC Node page.

[kalepail]

@ElliotFriend would love some thoughts here as I know you're restructuring all our docs right now

[ElliotFriend]

I'm actually working on this right now!! great timing!

Turns out it's quite trivial to add some synchronized tabs throughout the getting started pages, so that anyone could still copy/paste their way through without much trouble or thinking at all. Essentially, doing exactly this, as suggested by @chadoh:

... add a section at the top of 2. Deploy to Testnet that explains ...

I think since the instructions can be unintrusively presented both ways, it makes sense to provide as much useful info as possible. I should have a PR preview ready in just a bit that would be awesome to have some feedback on.

I'm unfamiliar with Divio's doc system, but at first glance it looks like a really awesome framework to think through this.

[ElliotFriend]

Here's the preview from stellar/soroban-docs#659, would love everyone's thoughts on this: https://soroban-docs-pr659.previews.kube001.services.stellar-ops.com/docs/getting-started/deploy-incrementor The deploy-incrementor page demonstrates what it ends up looking like.

[chadoh]

I like it! Thanks @ElliotFriend!

Still seems useful to have an explainer at the top of 2. Deploy to Test Network. Could be an info box or just a paragraph/bullet points.

[ElliotFriend]

Thanks @chadoh! There's a bit of explanation I added to the Setup page, since that's (likely?) where people would first be faced with the decision.

The page that actually talks about deploying to a test network does seem like a place where the explanation might fit (or be expected by someone), though... I'll add it there!

[chadoh]

Ah, I see! No, I like where you have it! I would maybe just give a little extra info to help people think through which to use. I liked Leigh's bullet points above. For Testnet, you might want to mention the benefit of being able to deploy apps that other people can try out, rather than needing to run it locally.

[leighmcculloch]

+1 as long as we keep it brief a brief enumeration of when to use one or the other would be helpful. Noting that one requires docker.

[ElliotFriend]

I'm not sure if I kept it brief enough: https://soroban-docs-pr659.previews.kube001.services.stellar-ops.com/docs/getting-started/setup#configuring-the-cli

Thoughts? @chadoh @leighmcculloch

[chadoh]

I think that's good enough for now. I wonder if a table would be possible, like one that compares versions of a product.