Provide Feedback on Rholang Tutorial

[TrenchFloat]

Let's give helpful, detailed feedback on @JoshOrndorff's Rholang Tutorial.

NOTE: Joshy's tutorial and this issue both target those who do NOT know rholang! Whether you have never written code before or simply haven't learned this language yet, the goal of this tutorial is to get you writing in rholang. If it doesn't, your feedback is valuable!

A new and improved version of the rholang tutorial will be released at the start of RCon3 (Sept 5) or a few days before. Joshy and I are looking for 6 or more reviewers of the Rholang Tutorial to work through the 12 lessons and write detailed feedback on what could be more clear or on anything that isn't straightforward. The key word here is detailed! Feedback should include visual appeal, word choice, suggested intermediate steps, any undue assumptions made on the reader's coding knowledge, or pitfalls experienced along the way.

Once the tutorial is released, Reviewers will start GitHub repositories for working through the examples of the lessons. Written reviews can be posted to the repositories, and are most helpful if done in chunks. A reviewer can give feedback on all 12 lessons right off the bat, and continue to participate by responding to updates on the tutorial, or he/she can review a few lessons at a time. Review of the tutorial should continue until the launch of mainnet or until Joshy is totally satisfied with the product, whichever comes first.

Joshy is holds one office hour each week at https://zoom.us/j/6853551826 to give support to anyone working through the tutorial (whether reviewing or not) and hear their thoughts. Rewards will be based on the more formal written reviews, though these weekly conversations would be to a reviewer's benefit.

If you are interested in reviewing some or all of the anticipated rholang tutorial, please assign yourself to this issue! No commitment necessary.

Budget and Objective

Reviewers contributing fully will receive a proposed reward of $150 each month, for a (proposed) potential of $600 for the four months until the launch of mainnet. Reviewers can also write on some but not all lessons for less than the proposed reward. Rewards scale with amount & quality of feedback.

Estimated Budget of Task: $3600
Estimated Timeline Required to Complete the Task: Sep. 5 to Launch of mainnet
How will we measure completion? The tutorial's works effectively to Joshy's satisfaction

[allancto]

@TrenchFloat i strongly support this. From what I've seen of Joshy's work it's high quality and I believe everyone who participates will learn and will become more fluent with the technology.

Thanks for posting this.
-@allancto

[TrenchFloat]

I'm glad to see interest in this issue! Just to confirm, @Ojimadu, @Viraculous, and @David405, none of you know yet how to code in rholang?

[mjreitz]

I'm interested in helping as well! I don't have any experience in coding so I can help with making it as user-friendly as possible.

[Ojimadu]

@TrenchFloat I could write some basic smart contracts at this point.

[ogini1]

I'm interested in this issue, and I'll like to provide some feedback but I can't assign myself.

[David405]

Hi @ogini1 I presume you are new to RChain. You are not yet a collaborator on this repository and thus may not be able to assign yourself to an issue, send to mail to [email protected] to request a collaborator's role and also register on www.rchain.coop to become a member of RChain.

[David405]

@TrenchFloat my proficiency level with rholang at this point is intermediate.

[TrenchFloat]

@Ojimadu @David405 The target participants for this issue are those with no experience with rholang - but your feedback is just as valuable! But sure to denote your rholang experience somewhere in your reviews, and please help us find 6 non-rholang-developers! With myself, mjreitz, ogini1, and Viraculous (assuming ogini1 and Viraculous are not rholang coders) we have 4 - of course, the more reviewers, the better.

[ogini1]

Thanks @David405 I appreciate the help I'll do that now

[BelovedAquila]

I am interested in participating and helping on this, I have no Rholang experience.

[Keaycee]

I'm interested to review all of the rholang tutorials. Although i have no knowledge on rholang. But i'm open to learn. @TrenchFloat

[Keaycee]

Can we get started through

[Tonyprisca13]

Am interested in learning @TrenchFloat

[TrenchFloat]

@Keaycee Joshy is releasing a new version of the tutorial very soon. Of course, you can let Joshy know your thoughts anytime, but he could have already tweaked the item you tell him about, so feedback will be most helpful after the new release.

[pmoorman]

@Viraculous @David405 @allancto and possibly others, there are a lot of comments above here that have nothing to do with giving feedback on Joshy's tutorial. Can we (you?) clean that up, so the issues stay focused on their scope? Thanks!

---

@JoshOrndorff I made it 80% down the tutorial before my flight landed. So I stopped a little short of the end 😉. On the whole, I think the whole thing is excellent (as I've said in DM before)!

Feedback

Text fixes
(Cmd+F on the string between "quotes" to find and replace quickly)

…“mow many pushups” => how many pushups

…“that we just learned discussed” => that we just discussed

…”next unit” => next lesson (you’ve called them lessons before, which makes more sense than units. Or maybe there’s a difference, but doesn’t look like it)

… “can only be snet on” => can only be sent on

… "prevent Ewritten onve from” => prevent Eve from (I wonder where the “Written on” was supposed to go :D)

In a few images "<” should be “<“ (in an image about the evil pizza shop, and a few times similarly further down)

Small issues

• What is the RNode REPL? When it’s first encountered, it’s not explained
• Bound & free names => I got confused about what “bound” means when I saw the first example. The text below it should maybe come before the example. Then it’s easier to (first the explanation, then the example)

Next steps (suggestions)

Maybe it's helpful, or maybe it's not. Here's how I would probably think we should further develop these resources:

• As a marketer (and in trying to understand the entire platform) I would be very curious to learn how these Rholang concepts translate into value props like concurrency in execution, maybe this notion of "correct by construction" and similar things. I imagine this might be too early, but could be a sort of "advanced" course.

• ... Or maybe you want to keep the tutorial solely focused on Rholang itself, in which case we shouldn't do that.

• If it's of any help, I would like to see if I could help turn the learning environment into something that can grow a little further. I imagine if we could support multiple "courses", that's the next step. I imagine something like https://www.vuemastery.com, although that's arguably a big step to make.

• Needless to say: there might be more complex Rholang topics that could be tackled in advanced lessons.

• For me, integration with some rudimentary code environment as well as cheatsheets, etc. would take it to the next level (especially as lessons get a bit more complex).

Anyway, hope it's helpful!

Best,

–Pieter

[pmoorman]

Maybe helpful to other people also, here's Joshy's repo of the project (so you can create a PR with changes): https://github.com/joshorndorff/LearnRholangByExample

[TrenchFloat]

@JoshOrndorff and I will be around (https://zoom.us/j/6853551826) at 7:00 AM Seattle time on Thursdays to gather and collect feedback/help out with the tutorial. Of course, feedback is welcome anytime!

[JoshOrndorff]

Looking forward to seeing everyone in office hours. Come with any content questions or feedback you have. We'll code together, learn from each other, and possibly spend a small amount of time discussing this bounty. The primary content will be about rholang itself

I agree we should keep the discussion focused..

[TrenchFloat]

This week we'll have a loose topic of discussion - lesson 0-3 of the Rholang Tutorial. Please come on Thursday with feedback, questions, and ideas for these lessons. Of course, discussion is not restricted to these topics!

[Viraculous]

@JoshOrndorff is there a prerequisite file to be installed before running the "rnode eval intersection.rho" instruction? I am getting an error note #File not found.

[JoshOrndorff]

To be most helpful, I'll need to see exactly what command you typed and exactly what output you got.

Before you can use rnode eval you need to have a running node (standalone is fine). I've given some details in lesson 0 about setting up the development environment.

https://github.com/JoshOrndorff/LearnRholangByExample/blob/master/0-DeveloperEnvironment/README.md#local-node

If you're really stuck, use rchain.cloud for now and come to office hours Thursday morning at 7:00AM Pacific time.

[JoshOrndorff]

I'd like to revive this issue. @TrenchFloat Can you continue to help me manage this issue?

[TrenchFloat]

Absolutely, @JoshOrndorff - sorry to let this issue get a little dusty. I've been taking some informal notes on Joshy's Thursday office hours (except 10/4, when I was absent), but it seems those blocks of time have veered into topics not tutorial-centered. We'll have to focus more on independent reviewing and feedback-giving, it looks like.

Joshy, could you clear up what form you'd like reviews to be in, in order to be rewarded? You mentioned keeping independent GitHub repos for the tutorial. Is @pmoorman's comment reward-able?

[TrenchFloat]

I'll throw out a proposal for rewards for this month. Discussion welcome (as always).

@pmoorman made it through 80% of the tutorial. 150*.8= $120 for Pieter this month.
$100 to myself and @JoshOrndorff for start-up and organization - expected reward to be much less for me the next 3 months, and more for Joshy, who will be implementing all the feedback.

I haven't seen any tutorial-specific feedback in Joshy's Thursday hours, so I'm considering that separate from this issue. I'm open ears to examples of tutorial discussion on 10/4 which I missed.

[JoshOrndorff]

@TrenchFloat The budgets you've asked for you and @pmoorman are low enough that I'm totally comfortable with them. I'm paid through SOW so I won't need any bounty payment. I've voted $220 (100 for you and 120 for Pieter as you've suggested.)

I never bring an agenda to my office hours. Rather we talk about whatever the attendees bring. So if you want to talk about the tutorial, please bring it up. I'm totally fine with that. I'm also fine with talking about other rholang related ideas.

Pieter's comments are quite valuable, but moving forward I will not accept comments written here. Each reviewer should fork my original github repository (https://github.com/joshorndorff/LearnRholangByExample) complete the examples, and provide corrections and suggestions as pull requests. If anyone is struggling to do that or doesn't know github well enough to do it, please ask during colab or hit me up directly.

I will not accept "I did the work but didn't make the PR, here's a link to some other format".

[ogini1]

@JoshOrndorff I would like to know if it is enough to use rchain.cloud for the tutorial since that would be most convenient at this time.

[ogini1]

For me, that is.

[JoshOrndorff]

rchain.cloud is pretty much sufficient. Just remember that you will not have your own personal tuplespace to play with there.

[Barkov-F]

In tutorial on developer environment (lesson 0) REPL stands for (run execute print loop). I thought it should be "read" instead of "run". Can I also suggest to add a link to the ItelliJ idea rholang plugin? Great tutorial, I will keep on reading it attentively.

[rolandkofler]

@JoshOrndorff it's not on github pages, is it published somewhere else or in maintainance?
https://joshorndorff.github.io/LearnRholangByExample/lesson1-SendingAndStandardOut/index.html

[JoshOrndorff]

@Barkov-F I've fixed the REPL acronym. Thanks for pointing that out. Is the IntelliJ plugin a complete way to run rholang or is it syntax highlighting?

@rolandkofler You're correct, it is not on github pages. The best palce to read it right now is directly from the README files. It is also kind of hosted at rchain.coop/learn-rholang, but sadly it is not kept up to date there.

[Barkov-F]

@JoshOrndorff The plugin is for syntax highlighting, right. So I guess it doesnt belong to runtime env, but the section is called "Developer Environment" and I thought it would be ok to include it. So I did in RUS variant of the tutorial.
One more question: is it terminologically correct to call !, !! and such "operators" or there is another term for actions performed on channels?

[Barkov-F]

In Receiving lesson an exercise for coffeeShop.rho says "Order a second drink" but in code there are already two drinks. May be change that for "a third drink" or just "more drinks"?

[JoshOrndorff]

@Barkov-F I'm not 100% sure whether it is "correct" to call ! the send operator, but it sounds fine to my ear. I can't think of anything more correct to call it.

"order another drink" issue, you can fork and make a PR. Then you'll be earning some of the available bounty and saving me manual work.

Anyone else who wants bounty can also make those PRs.

[JoshOrndorff]

Congrat to @Barkov-F who was the first to express interest in this bounty and create a PR JoshOrndorff/LearnRholangByExample#20