Review of Rholang tutorial by casual Developers

[dckc]

The recent SDK 0.1 release included a Rholang Tutorial.

It concludes:

We hope that the foregoing examples spark a desire to write more code and demonstrate the ease of expressing concurrent designs.

The 0.1 release is primarily aimed at early adopters, as Medha noted in her Feb 2 comment, but it doesn't hurt for more casual developers to review the tutorial and see where its strong and weak points are.

@TrenchFloat and @JieL314 and others:

1. As you read the document, what is the very first phrase or sentence that doesn't make sense?
2. In your first full read of the document, which parts make sense and which do not?
3. Read it all the way through at least twice and then go back over some parts that interest you or puzzle you. Now which parts make sense and which do not?

[dckc]

How long did you spend looking for installation and compilation instructions? Please look a bit more.

Hint: they are two links away from the tutorial.

If there two links are hard to find, please report that via gitter or open a jira ticket.

p.s. the tone of your writing suggests that you are entitled to have others address these shortcomings for you. That would not be a welcome attitude. I hope that is not what you meant to communicate.

[cenyuhai]

The tutorial is too simple, I don't know what I can do with Rholang... It also make me confused. This example for Mutable state is too long. There are too many Secure design patterns. 2-3 design patterns will be better. we should have a tutorial like https://solidity.readthedocs.io/en/develop/introduction-to-smart-contracts.html

[David405]

@dckc, dont misinterpret my statement. I only meant we need to work on more documentations and tutorials for will be easy to understand for developers but robust at the same time, you can see the complaint @cenyuhai is stating, I am pretty sure many other developers encounter the same problem

[David405]

I am not saying Rholang should change its pattern or structure, all I am clamouring for is more documentation

[David405]

@dckc, I sent you a pm on discord, please I will be awaiting your reply

[dckc]

@cenyuhai which parts make you confused? What is the very first phrase or sentence in the tutorial that doesn't make sense?

Thanks for the feedback on the length of the Mutable state example; I have seen discussion of Rholang language features that would allow it to be more concise. Your feedback confirms this is important to do. Here's hoping for time to check when that feature is scheduled and such...

Marc Stiegler's A PictureBook of Secure Cooperation is well known in the capability security community. I think capability security is critical, so I was happy to see all of the examples worked out in detail. But for a broad audience, perhaps you're right that it would be better to do one or two of them in this document and move the rest to a document specifically about capability security patterns.

As to the solidity tutorial... many of the smart contract features of Rholang are still in development. I think it's great that we can preview the tutorial for the mercury release, since the core team shares their work via github.

[dckc]

@David405 writes:

... I only meant we need to work on more documentations and tutorials ...

Yes, and we have #298 where we can discuss that; let's keep this issue focused on what I put in the description, please.

[David405]

okay @dckc sorry for digressing, I am currently doing a compilation and intense study on all the Rholang documents,I will drop a comment on it once am done

[TrenchFloat]

1. "Rholang is completely asynchronous, in the sense that while you can read a message from a channel and then do something with it, you can't send a message and then do something once it has been received." (Keep in mind my neglible amount of experience in javascript) Why not? Would I have been able to do something with the message anyways if it was sent somewhere else?
2. The "Receiving Data" heading starts at bullet 2. I could generally follow along up until "Mutable State." "Maps" and the dining philosophers section also made sense.
3. After some googling, I found out what a channel was and "Maps" and the beginning of "Mutable State" were clearer. Again, calling myself a "casual developer" would be speaking highly of my knowledge in the area.

[Jake-Gillberg]

Whether we use name(process) or name!(process) to represent a "send" is inconsistent.

All of the tut-* examples in rholang/examples use the name(process) syntax, and the code examples on the website use both (ack!).

I got confirmation that there is no difference between the two in discord, which turned into a slight discussion about what syntax should be the standard.

In any case, the website should probably be updated to reflect the code in the examples (or at least be consistent in it's own usage). (It would be awesome if the code examples were pulled directly from github, or if I could open a pull request to developer.rchain.coop...)

[dckc]

It would be awesome if the code examples were pulled directly from github, or if I could open a pull request to developer.rchain.coop...

agreed; see #411

[dckc]

@MParlikar did I show you this feedback?

[zsluedem]

We should make pages for the basic concept like "what is process in Rholang? what is contract in Rholang? What is channel in Rholang" . etc And also the basic data type about how declare Map, List and something like that~!

[dckc]

I closed the loop with Medha and Kelly F.