Ahoy ICP hivemind,
Inspired by community feedback, this week @ais and I have been working on completely reworking the first developer experience of the developer docs. There is a bigger docs redesign currently in the woks, but I wanted to improve what we currently have.
I created a tutorial. I want and need harsh, no-bullshit feedback so it can be super streamlined. No feedback, typo, nit is too small. I would be very grateful.
[How to deploy a "hello world" smart contract/dapp in 20 minutes :: Internet Computer]
It has been clear from the developer forum and anecdotal experience that IC’s developer onboarding is rough. It’s important to accept reality and that is the harsh truth. This roughness comes in two forms:
- Documentation that does not provide a great experience
- Developer-facing tools that force odd paths or are wonky to use
I am working on #1, and the intent is that by laying out all the steps for onboarding, it can also help the redesign and developer experience of the SDK.
The immediate goal is to have a tutorial that could take a curious developer from 0 to “hello world” in as few steps as possible, in as few rabbit holes as possible. To do that we did the following:
- removed unnecessary pages and tried to streamline the first developer experience
- Fixed some SDK issues
- Clarified to the reader what was happening when needed… but avoided overloading the reader with information when not needed
Please run through the tutorial and tell me what you think in this forum thread or make Pull requests I can review: GitHub - dfinity/docs: Documentation for writing code for the Internet Computer
This first entry point should be flawless and it is clearly not there yet, so your help is greatly appreciated.
Readers may note that some of the language attempts to optimize for clarity over precision. That has been my intent in the wiki as well and I think that has yielded good fruit: Internet Computer Wiki
Maybe I’m lazy but
I think it could be made more minimalist and broken up into multiple tutorials in multiple pages.
- Npm - link to npm
- dfx link to dfx
- Linux or OSX Intel
- dfx create test
- cd test
- npm I
Links to cool stuff:
- deploy to ic
- react in project
- coding exercises
On links to cool stuff we teach the concepts we are trying to squeeze into this article.
So they learn that info when they need it.
For me it was difficult to understand why the frontend and backend canister is in one project and how we can split it. Which parts belongs to the frontend and which to the backend, especially from the NPM packages.
I understand for a first try it makes sense to have anything in place, but if you come a little bit more in real case scenarios you will have at least different developer for frontend and backend, so we have to split the projects to create a development workflow.
Another confusing part I was facing was the relationship between the dfx identities and cycles wallets, so I was lost between different identities on my machine, and in the end I lost my overview about my deployed canisters and there identities. I’m writing currently on some article to make this point much more clear, at least for me.
This is actually an interesting point. You would need to have an npm job that packages the declarations for the front end devs to then import into their project.
Hey Diego, thanks for the effort, this is a great idea.
I agree that it could be nice to start with a simple
dfx new --no-frontend to teach the basic concepts of developing and deploying a simple smart contract and then later on add the frontend part of the process by running the default
Also I miss the part where it is explained how to access the local Candid UI which i find very helpful for debugging and how to access the frontend deployed to the local replica (
localhost:8000/?canisterId=...), not using
I left a PR in the repo as well
Thanks for the feedback, folks. I should have a new version this week that addresses your guys points. I agree with them.
maybe for the frontend part point to the frontend templates in the examples repo and the ones that @Tbd built GitHub - MioQuispe/create-ic-app: Use your favourite frontend framework with the Internet Computer.
in general some nice links for further steps could be helpful
Thanks to the community feedback, we have been able to massively simplify the quickstart dapp tutorial from 20 minutes to 10 minutes and fixed many bugs.
I haven not incorporated all the feedback yet, but making progress. Thanks everyone!
Make me think, would it be worth always using
http://canisterId.localhost:8000 rather than
http://localhost:8000?canisterId=... in documentation and tutorials? It seems less prone to issue.
Didn’t even know this works as well
Yeah the query param version was the solution displayed in the doc for a long time. Nowadays the doc displays
https://<canister-id>.ic0.app (for example chapter static website)
If I get it correctly, the local subdomain way helps if the app is bundled to ES modules - multiple chunks. It did the tricks for me and also solved a discord question I answered last week.
Sample apps are bundled to a single js file, therefore it works with both ways for these.
There are a lot of undocumented things that are hidden in this forum. Is there someone we can tag if we feel like a topic is worth being added to the docs?
Instead of tags, maybe directly opening issues on the docs repo?