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 
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
