So first of all I’d like to point out the things that I have loved about DAML so far.
I love that it is intended as a low-coding environment and that a huge amount of the boilerplate has been abstracted away.
I appreciate that the tools are open-source and free for a large number of cases. I love the VSCode plugin, the DAML assistant, the scenario codelens. All of this has made my life much much easier.
In terms of issues I’ve had a long the way (and bear in mind I only started 10 days ago and since I’m a non-coder some of these things are probably specific to my introduction to programming and others to DAML itself)
The documentation assumes a fair amount of previous programming experience I feel and also doesn’t stress the importance of Smart Contracts in DAML being a new paradigm. I discovered this by accident on the DAML Medium blog several days later. Had I understand that context before starting out on the documentation, it would have a) boosted my confidence and b) got me upto speed much quicker.
As I said already I discovered the blog by accident and for some reason, some posts are on Medium while others are on the DAML site. It seems a little fragmented and that makes it harder to follow. That said the content is excellent and is confidence inspiring so no qualms with the content. While this isnt directly linked to documentation, the blog provides very important context which is useful in the documentation itself
Side point. Have you considered posting any of the content to places like HN? The one about smart contracts being different to traditional application patterns would probably do quite well on HN.
There’s a step right at the beginning about setting up the paths for Java and DAML. This step isn’t working for many especially on Mac and Linux because most people have to set this up via a config file explicitly. I had to go over to stackoverflow to find the solution to this, scattered amongst a few stackoverflow posts. That increases the amount of time someone gets up and running with the SDK if they’re just trying to have a dabble
While I like the fact that “create-daml-app” is an easy to understand concept, in the real world contracts are more likely to be used for the transfer of value as mentioned on your blog posts many times. Personally, I think it would have been much more helpful to have an equally simple app but that is related to the transfer of value in some way (some sort of super basic finance app for eg). With a simple social network, the idea of contracts gets confused a little and one starts to associated some of the concepts with traditional application patterns. At least that’s where much of my confusion initially stemmed from.
This one is a little nitpick. There are a fair few spelling and grammatical errors in the documentation, which makes it harder to trust what is written there.
It left me glowing with pride both of you and the incredible team behind Daml.
We will take your suggestions about clarification of setup and perhaps better proofing of our written work going forward. We have contributors from across the globe who are writing articles in English where English is often their second, third or fourth language (and that’s not counting programming languages), but we can always find room to improve.
The most important thing is that you keep going forward with Daml.
We will be here cheering you on every step of the way!
Thanks for the detailed write-up! I’m not best placed to address most of those but I’ll make sure this feedback reaches the right people.
Regarding the PATH issue, this page is supposed to guide you through it. Is it not helpful as it stands? Is it too hard to find? Can you think of anything we can to do make it better?
Thanks for reporting the typos. I went quickly through our docs with a spellchecker and fixed a bunch of those (here). If you have any other fix, all contributors are welcome.
I’m glad it swelled your heart @rps . I have much confidence in DAML. It’s very clear a lot of thought has been put into the design philosophy behind it and that both inspires and reassures me every step of the way.
By the way, please do consider video tutorials for the more involved walkthroughs. I personally find the video tutorials over at Webflow university to be the gold standard of how video tutorials should be done for a product. I am absolutely in love with them.
@Gary_Verhaegen The page you linked isn’t hard to find, the issue is it misses a step/assumes certain things are already in place and therefore fails in practice.
Here are the two stackoverflow answers that gave me some insight:
One of the key things to keep in mind is the shell on Mac has now changed from Bash to ZSH so setting up the path for that requires a different config file as far as i am aware.
I also had to look up how to create the file and save the path info.
As an aside, I also had issues launching DAML studio the first time, the fix to which I found on the VS code website
I took a crack at clarifying these two sections. It’s not integrated with the official docs yet, but if you’re willing to take a peak behind the curtain, would you mind sharing your opinion on whether I’ve made things any better?
You can see the “rich diff” format of both changes here and here, as well as the “new version” format here and here.
Yes @Gary_Verhaegen , that is much better already. You might want to help people figure out whether they’re running Bash or ZSH as well. Just a thought.
I agree with @krmmalik especially with the disjointed locations of the posts relating to Smart Contracts and DAML itself. I too started on the blog, it jumped to Medium, then back again, which is fine so long as an internal document link on either platform links back exactly to the same link on either platform.
I guess that brings another question to mind: is the blog the canonical reference for events, developments and technical concepts, and Medium is only to garner a wider audience and product exposure?
In terms of the install document, I wrote a quick one for GNU/Linux Debian/Ubuntu (On Raspberry Pi & x86) that I will tidy up in the next few days, then post here/wherever. From SYSTEM_UPDATE to a functioning DAML with VS Code editor. I always do this with a new tech stack as invariably I’ll rip it out and start again … for familiarity, experience and fun
Good to see non-coders being strongly supported from the start
