Holochain Forum

What is missing in the basic exercises of holochain-gym?

I would like to start a conversation on what is missing or can/should be improved in the basic exercises of the holochain-gym
And broadly speaking what you think the focus/goal of the beginner exercises is/should be.

In my humble opinion, it would be helpful to have a common understanding of the objective of the beginner exercises.
So we know what to add or change and what to keep.

I’m specifically asking about the basic exercises, not the intermediate ones, because I’m convinced that the basic exercises should speak to a broad group of potential developers.
But feel free to voice a different opinion.

If we identify things we can do that are actionable we can create issues in the github repos, so people who are interested can pick them up.

3 Likes

Thanks for posting this @tixel and all your work on the gym - for me and I see others it’s been the most ‘fun’ approach to learning something new I’ve come across and that’s refreshing as although great documentation is great, fun is way more fun :wink:

To re-iterate my position on this. I am purposely including issues around my mental health situation as although I feel it’s a little “ooh look at me trying to be special”, it’s actually making a hell of a lot of stuff in my life pretty clear and I feel it’s of value as also don’t want to have to explain further my motivations as I realise some issues others may not have or experience as much. The main one I’m having is fitting learning into my schedule and with my executive function issues I often have to start at the beginning again each time, I think this can be improved with some of the suggestions I have here:

[Some things I am referring to are part of what I’m working on now, here’s a link to the changes I’m referring to]

  • Consistency and simplicity are key for me - if we’re learning how to “create” something but half the time we’re using the word “add/ed” I’m having to first understand and then re-member that relationship when I return to the exercise. We are creating, and it is being added - does ‘added’ need to be referred to or can we simply stick with ‘create’? I took the latter position however don’t know if it’s “right” or not, feels OK to me but perhaps create and add do need to be separate, that’s where I could do with feedback. This may or may not be to do with executive function, could be that I’m just noopid lol but it threw me a little even though I know it’s a basic thing. Generally different languages do similar things with different syntaxes so I guess I’m always focused on potential syntax changes (i.e. I’m always thinking ‘what’s the api call called’)

  • Not using words that are close to ‘reserved’ words, for example using the word ‘content’ for the field name for the content, hence my current changes from ‘content’ to ‘greeting_text’

  • Taking the opportunity to make people start to feel successful from the start and like they are part of the wonderful community I’ve experienced, which will hopefully lead to more growth, participation, and contributions. This is why I changed the first sentence of the first lesson to say “As a Holochain developer”, and a bit of a wild one but why I started to changed “Hello, World!” to “Holo, World!” which I’m not totally 100% sure about but seems like a missed opportunity if not done lol.

  • Being clear - I love the gym theme however I did find sometimes it confused the the learning - I found myself thinking "is this the gym story or is there something solid I need to be learning. The bit about being injured took me quite a while to figure out how to best re-arrange - I ended up separating it, putting it prominent at the beginning of the section, prefacing it with “NOTE:” to highlight importance, and put in italics as that has been a previous method used in this documentation to separate direction from learning.

  • Using the least amount of words possible. Along with my views on code (but seemingly not when writing my own replies to forum topics lol), I found this section particularly confusing “One thing you need to remember is that zomes are just modules, which means that by themselves they don’t do much. You need to feed them data and ask them to do stuff. To be honest, zomes can actually do a lot, even when you are you not looking, but that will become clear over time.” hence my current pull request changes all that to “By themselves, Zomes don’t do much - you need to feed them data and ask them to do stuff!”. Perhaps the autistic me is needing to be precise about ‘stuff’ hence my issue with the original wording - I’m still not 100% with the fact ‘stuff’ is in there still, but it’s better than ‘things’ lol. I also felt the switch between they don’t do stuff but they do even when you’re not looking goes ‘a little bit too far’ - I wanted it to be more precise and not edging on what I felt but know wasn’t meant that way but a little condescending - I’m a big boy, I can handle the truth, especially when it comes to Zomes and their functionality or lack of it until I give them some data lol. So my changes might have made it a little too concise and boring I admit, a half-way point between the two would be cool.

  • Link to ‘advanced’ references. There’s quite a lot of references to things we’re going to be learning in the future. My brain wants to know ALL THE THINGS so I’ve added links to glossary terms for a few reasons - what I found happening was I was googling them and then the ADHD meant I was down another thread and oh look another day’s gone by. So by linking to the more advanced concepts I’m providing the opportunity for the reader to check them out without leaving the tutorial or getting too advanced and leaping ahead. This has already helped me gain a greater learning of the concepts of Holochain / distributed app development.

  • Holochain vs holochain - just writing that above reminded me decide on which is it (‘Holochain’) I believe and stick to that - it’s a brand, it’s a symbol, to me saying ‘holochain’ makes it more ‘verby’ whatever that means lol. Same with anything else that’s a product or service name or part of the brand / thing you’re growing.

  • Being precise - In the ‘try it’ section it says ‘in the details you will see three things… the hash is the last of the three’. First I changed ‘details’ to ‘Entry_Contents’ as it is named (I mistakingly first changed it to Entry_Details). We all know it’s the details, but when my limited executive function is looking at the screen, reading the tutorial and so on, the link between knowing what the details are and just stating the thing I’m seeing in front of me helped me just do the thing not have to think about the thing - does that make sense? It sounds like such a silly little point but now I am beginning to understand why this stuff takes me longer lol, being precise like saying ‘in the Entry_Contents’ rather than the more generic ‘details’ term lessens the amount of things needed to be figured out. Then it says the hash is the third thing when to me it seems like it’s the first thing:

  • Making use of lists and whitespace. As you may have gathered, I tend to notice details and over-analyse. I found the chunky paragraphs hard to understand as I had to take them apart, work out the meanings - is this storying, fact, etc., then apply. Listing steps you want people to do is also good as it makes things clearer, is quicker when returning to a topic, and provides good ‘whitespace’ separating narrative from doing things.

As for purpose of the beginner exercises I think this format is great for both introduce absolute beginners / hobbyist right through to the professional coder. I believe all of that spectrum is important as I have seen how empowering everyone who wants to learn can result in things you could not imagine, from experts in their own specialist field adding value in terms of things like innovation and introducing different communities whom you wouldn’t normally connect with in terms of commercial or tech connections. People who just want to build stuff for their own use, don’t have budgets or justification for them. Some I’ve seen go from that to very successful business owners, some who’ve developed functionality or fixes that couldn’t have been seen or imagined anyway I think you have the point lol. So that’s why I did things like add the link to the “Hello, World!” wikipedia - silly little thing but also realise “older” info like that might be being lost to both younger generation of coders as they grew up in walled gardens, and to the new person who hasn’t coded before. Both those I see in the Holochain community already which is absolutely fantastic!

On that note, I am not in a position to say whether the level of entry as to what to actually learn is ‘correct’ - first I am still on this first lesson of entries lol as surprisingly enough I’ve been distracted but as I learn more I’ll be able to comment whether it’s a good starting point or not. And as I’ve learned many languages before I don’t know what it is for a beginner, perhaps list some pre-requisites. I don’t think you have to go to the extreme of being the portal for the potential programmer, however I do think you will attract them due to both the nature of the project providing interest from all walks of life, and how it’s being delivered via hardware and hosting.

ATEOTD the long-term success of this project is going to be down to the growth of a community that can grow and sustain it past the length of your life and mine, and that takes all types, including verbose b*stards like li’l old PDA me ;0) (I’m one of the voices on the 1min intro to PDA video on that site lol… often misunderstood!)

HTH & thanks again for all your ingenuity and hard work on this. I have a lot to learn both code & community-wise, I realise I am a little OTT sometimes, I am working on this… and at the moment, doing this is helping in a weird way…

sbp

2 Likes

Free weights.
JK
Can you maybe paste a link to that gym?

Hi @toledoroy,

Holochain-gym is a community project started by @guillemcordoba. It strives to provide some basics exercises to learn to build holochain apps.

I edited my initial post and added the links.

1 Like

Thanks for the link

Some quick errors:

  1. I’m not getting a logo
    image

  2. Broken link
    image

I tried running through the gym and didn’t get very far…

I ran the setup step, which is just cloning a repo. Then moved to the next step and I’m not sure how this is related to the repo I just cloned since it seems I need to clone a different repo for that exercise.
I don’t feel like I really completed the setup, because usually after running a setup procedure I’d have a working environment, but all I got here was a repo clone…

I think the first stage should set up a clear, working, and verifiable baseline to work on. Whether this gym is meant to be a sandbox app or something like that, first it’s important to have something working and to make sure we’re on the same page.

Second, I think it would be extremely valuable if you want to get developers that aren’t yet professional holodevs to be able to use this, is to start with some kind of a simple dictionary that explains all the special semi-medical terms that you’re using and correlate them with the commonly known computer software terms. Even after watching a few HC videos, I still have trouble remembering what each term means, and since minds index by first letter, and you’re using terms that lack the beginning (chromo)zome it would really be valuable to have a holodev cheatsheet available at all times. (I would make one myself if I could)

Videos are nice when you want to present a procedure, but generally, I find clear and clean written instructions more valuable for explaining basic terms and functionality. I think that more written material and working demo code would be the most valuable at this stage.

1 Like

Hi @toledoroy,

I’m not sure if I understand you correctly, but could it be you also cloned this github repo?

https://github.com/holochain-gym/holochain-gym.github.io

This contains the website and should not be cloned. You can just go to https://holochain-gym.github.io and read everything there.

The only thing you should clone is

https://github.com/holochain-gym/developer-exercises

But perhaps I mistaken. If you can post a specific error in the hologym help wanted thread, we will try to help you out.

A part from that: thank for your feedback. I’ll make a list of everything we received as feedback below in this thread.

I think improving the setup might be a good thing to focus on.

Below is some of the feedback we received, in this and in other threads, on the gym. Thanks for a the feedback.

  • make gym easier to find
  • explain anatomy of folder structure
  • introduce the pertinent elements of hdk::prelude at the top
    of each exercise + show useful rust hdk code (or link to it).
  • in hashes exercise -> explain how to get hashes in and out of zome
    cfr. EntryHashB64
  • explain Wasm and Wasm errors that you need to throw
    –> .ok_or(WasmError::Guest(String::from(“Could not find book”)))?
  • show working simplified code examples before starting to explain exercise
  • first stage should set up a clear, working, and verifiable baseline to work on
  • kind of a simple dictionary that explains all the special semi-medical terms that you’re using and correlate
  • Consistency and simplicity in language use
  • Not using words that are close to ‘reserved’ words
  • Tone down the gym references as it can confuse/distract from the learning
  • Don’t make explanations too long or muddy
  • Making use of lists and whitespace

Clean, concise and compact language and a good setup experiences are two things that stand out to me.

3 Likes