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.
Summary
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.
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.
My goal
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
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
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 dfx new.
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 npm start.
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.
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?
