[WIP] Data-structures tutorial (closes #57) #59

mikeal · 2018-10-02T21:17:30Z

This is not finished but feedback is welcome.

todo · 2018-10-02T21:17:37Z

example in JS.

https://github.com/ipfs-shipyard/proto.school/blob/28e4a7803159966aee6a60263a9e2d74a4a61e5f/src/lessons/Data-Structures/01.md#L25

This comment was generated by todo based on a `TODO` comment in `28e4a78` in #59. cc @ipfs-shipyard.

vmx · 2018-10-04T12:18:53Z

I've read through the markdown files and I don't have more to say than: great work!

terichadbourne · 2018-10-22T21:16:05Z

Addresses issue #57

terichadbourne · 2018-10-23T16:23:25Z

I'd love to discuss this in more detail with you when you're back, @mikeal, but here are some first impressions and questions after a quick read-through of the current draft of this workshop, shared in the interest of making this content as beginner-friendly as possible:

When introducing data structures in general (lesson 1), it would be great to mention some common examples that developers will be more familiar with. Of those listed in the Wikipedia article, I think arrays, objects, and graphs would be the most recognizable to a web developer. I'm suggesting mentioning them in passing to make the reader realize they already have some fundamental related knowledge, not going into any detail.
Decentralized data-structures are collections of data-structures that are linked to one another. Is it really true that linked data structures are decentralized, or is it more accurate to say that linked data structures are particularly well-suited for decentralized networks? (Lesson 1) Is the reason that they're well suited (for cases like git) the linked-ness or the consistent hashing so you're guaranteed everyone's using the same data? Or are both equally important?
This allows one data-structure to be distributed over many different computers and protocols. Is it really true that the data structure is distributed, or is it that the data is distributed over / copied onto many computers, and the data structure is the key to ensuring we all know how to interpret that distributed data? (lesson 1) Note that I'd feel differently if you'd written "structured data" instead of "data structures" here.
I don't know of any reason to hyphenate "data structures," and it's not hyphenated in the Wikipedia article. Are you trying to convey a new meaning by hyphenating it that I'm missing?
When learning new concepts, I find that contrasting them to things I'm already familiar with is really helpful. Two opportunities for us to use this teaching method here would be to specifically name and describe centralized networks (versus decentralized networks) and location-based addressing (versus content-based addressing). Calling out these contrasts would be an opportunity to highlight the "why" behind decentralized (security, etc).
I'm not sure it's fair to assume that people know what a hash is. (lesson 1) If you're not familiar with cryptography and you know Ruby, you might think it's the equivalent of a JavaScript object, for example. I'd love to see more here about how you're turning your photo of a kitten into a string of characters (hash) that represents that picture of a kitten, emphasizing that every time you do it to the same pic, you get the same hash back.
It's not yet clear that when you change a single pixel of that kitten photo, the hash changes. This could be addressed somewhere in Lesson 2. Perhaps Bob changed a word/pixel in the doc he received from Alice, for example, so now it would have a new hash. You have to understand that a single change to the data changes its hash before you can understand the statement in lesson 3 that As this tree above is built the final content address (hash) of the root node is unique to a tree than contains every node all the way down this tree.
You may just not have gotten to it yet, but I hope to see more about what DAG means, particularly since all the commands we see later include dag in them. My impression from reading elsewhere is that IPFS is a combination of merkle-ness and dag-ness.
Should definitions of and differences between IPFS and IPLD be discussed in this lesson? IPFS is mentioned once with no description of what it is. IPLD is never mentioned that I've spotted. These definitions could (a) be mixed into the content of these existing lessons, (b) be another lesson in this series, or (c) be another series that comes after this one and before people start working with the IPFS commands in the Basics series.
Should we say something about what formats of data can be stored in IPFS / decentralized data structures? Does this hashing system work equally well for pictures and text documents and JSON objects? Does it somehow store the file extension so you can figure out how to turn it back into a kitten picture on the other end? This might go in the IPFS/IPLD section as opposed to specifically the more general section, if we do make a distinction there.

Happy to answer any questions about my questions when you're back.

terichadbourne · 2018-10-23T16:34:25Z

Just spotted your convo with Paul about decentralized data structures and there may be some language there that we could pull in as well: https://twitter.com/pfrazee/status/1054431271986913280

terichadbourne · 2018-10-23T19:59:13Z

Note that due to a change I'm making elsewhere, we'll need to update the last lesson in your series (once we know which that is) as follows to ensure it links to the workshop list instead of a non-existent subsequent lesson:

Add last="true" to the values being passed to the Lesson component. (The button will now populate automatically.)
Use the success message "Great job! You've completed this series of lessons!" or something else that makes it clear this was the last lesson in the series.

terichadbourne · 2018-11-09T15:16:34Z

@mikeal How would you like to approach finishing up this lesson? Do you want to hop on a call and chat through the first impressions I've shared here?

terichadbourne · 2018-11-16T18:04:50Z

With a revision I'm making today in PR #83, you'll no longer have to add last: true as I'd previously indicated.

mikeal · 2018-12-13T19:45:06Z

Pushed some new stuff. Responses to your earlier points:

Added a sentence.
Write a new section on verifiability and re-worded this sentence.
It is actually true that, quite literally, the structure of the data can be spread over multiple peers. Each peer may only have part of the data and the organizational structure of the data is only clear if you have all the data. Re-worded this sentence a bit tho.
Fixed.
We contrast URL (centralized addressing) with content addressing in the second lesson. Is this not sufficient?
Added a link to Wikipedia. The TODO code sample should help here too.
Added more language to this effect in lesson 3.
DAG's are merkle trees :) I'll make sure to address that in the lesson.
Perhaps that's what the lesson should eventually close with.
We could talk about this but it very quickly gets into fairly advanced topics. I'm not sure if we want to go down this particular rabbit hole.

- Resolving merge conflicts to get the data structures lesson into the new site format

- Pulling in latest update removing dummy chapters

- Refactor lessons / components / routes included in tutorial - Add more pages to better section the content - Pass lesson titles to Lesson.vue - Add content on traditional location-based addressing

- Add a new section that appears when no exercise is present and use it to display a conditional button that shows "Next" or "More Tutorials" depending whether it's the last lesson in the tutorial. - TODO: Fix page formatting so button is aligned with right edge of text

- Center content to match rest of site - Put the question link in a new footer - Other layout tweaks

- Move `issueUrl` from `data` to `computed` in `Lesson.vue` and make it return a string with spaces instead of dashes (Eg "Data structures") - This also fixes the titles of issues opened by clicking the question link in the footer

- Update data structures tutorial to be more beginner-friendly

- Fix a typo that was making the submit button invisible

terichadbourne · 2018-12-20T20:52:27Z

@mikeal I've gone through and reworked the existing lesson structure and content to something that feels more beginner-friendly to me. Could you please take a look to make sure I haven't introduced any inaccuracies?

We had discussed the possibility of adding a final lesson introducing IPFS and IPLD, but I think you should be the one to do the first stab at that if we want to add it.

I feel like the linking stuff is clear now, and it's obvious what content addressing has to do with the distributed web, but it's not super obvious why we're talking about merkle trees and DAGs. If you have ideas for fixing that, let me know!

There's not currently much of a conclusion here, but that's in part due to my finding the last section the least easy to explain the importance of in this context.

I'm comfortable merging this tutorial now, but after the holidays I'd like to ask the non-developers in the company to read through this whole tutorial and tell me what's confusing. I did my best to keep the language accessible to non-programmers.

- Add customized nav to lesson component. This special one loads if the current path isn't one of the ones in the nav bar (not a long term solution) but currently accurate for judging that it is a lesson page - New nav shows breadcrumb-style access to home and tutorials and displays workhopShortname

- If there's no exercise, the next or more tutorials buttons will mark the lesson complete

terichadbourne · 2019-01-02T14:15:25Z

@mikeal This PR to finish off milestone 1.0 is awaiting your approval. I'd appreciate you checking to ensure I haven't introduced any inaccuracies while trying to simplify the content of the new tutorial. Thanks!

terichadbourne · 2019-01-02T14:56:51Z

This also now closes #107

src/lessons/Data-Structures/01.md

mikeal · 2019-01-02T17:49:07Z

src/lessons/Data-Structures/01.md

+or on disc. But in a decentralized system you have less, or possibly zero, trust among peers.
+
+Also, large data structures need to be able to be spread out among peers and <strong>linked together</strong>
+in order to be decentralized. In the same way that any web page on the web can link to another web page


Can just say "any web page," "any web page on the web" is a bit redundant.

src/lessons/Data-Structures/03.md

mikeal · 2019-01-02T17:55:41Z

src/lessons/Data-Structures/03.md

+of those two photos is identical.
+
+<strong>Cryptographic hashes are also unique</strong>. That means that if Jess uses Photoshop to remove a
+single whisker from that kitty, the udpated image will have a new hash, and it will


Suggested change

single whisker from that kitty, the udpated image will have a new hash, and it will

single whisker from that kitty, the updated image will have a new hash, and it will

mikeal · 2019-01-02T17:58:23Z

src/lessons/Data-Structures/03.md

+access to that image.
+
+The decentralized web works differently. When we want a specific photo of an adorable pet, we ask for it
+by its content address (hash). Who do we ask? The whole network! If Kyle is online, we'll see that he has


At this point I completely had forgotten about Jess and Kyle and had to scroll up to remember.

src/lessons/Data-Structures/04.md

mikeal · 2019-01-02T18:02:46Z

src/lessons/Data-Structures/04.md

+A `CID` is a single identifier that contains a cryptographic hash **and**
+information about how to interpret that data called a "codec." (Codecs encode,
+decode, compress, and decompress data in certain formats. You use them every time
+you stream a YouTube video of an adorable beagle.)


Video codecs, like those on YouTube, are a different beast, so I'd leave this out.

In fact, we already have be aware of video codecs when encoding files in IPFS, just at a different layer (chunking).

src/lessons/Data-Structures/04.md

mikeal · 2019-01-02T18:04:29Z

src/lessons/Data-Structures/04.md

+giraffes. The possiblities are endless!) All the way down this tree we
+have cryptographic hashes that allow us to distribute and link the data.
+
+Why is important to link between different data structures? Every day on the centralized web,


Suggested change

Why is important to link between different data structures? Every day on the centralized web,

Why is it important to link between different data structures? Every day on the centralized web,

src/lessons/Data-Structures/04.md

src/lessons/Data-Structures/05.md

mikeal · 2019-01-02T18:07:44Z

This is great!

I'd say that the changes you made have made this tutorial 8-13x better than the original :)

I've added a bunch of small comments in-line as well as a few suggestions.

- Address typos - Change HTML to markdown formatting - Remove reference to compression/decompression and videos in explanation of codecs

- Edit character names in decentralized data structures tutorial

- Fix typo in data structures lesson 3

mikeal added 2 commits October 2, 2018 14:15

fix: enable lessons without a code sample

cdb8487

initial: data-structures tutorial

28e4a78

merge: fixing conflict in no-exercise case

25bdc04

doc: merkel trees docs

67c3e10

terichadbourne mentioned this pull request Oct 22, 2018

Create decentralized data structures tutorial #57

Closed

weekly-digest bot mentioned this pull request Nov 11, 2018

Weekly Digest (4 November, 2018 - 11 November, 2018) #81

Closed

weekly-digest bot mentioned this pull request Nov 18, 2018

Weekly Digest (11 November, 2018 - 18 November, 2018) #85

Closed

mikeal changed the base branch from master to code December 5, 2018 22:42

fix: merge conflict and other updates

4dac621

mikeal and others added 9 commits December 13, 2018 11:53

feat: added description of DAGs

32051ac

Merge branch 'site-structure' into data-structures

3fab529

- Resolving merge conflicts to get the data structures lesson into the new site format

Merge branch 'code' into data-structures

4dcd00e

- Pulling in latest update removing dummy chapters

Refactor Decentralized data structures tutorial

9efb415

- Refactor lessons / components / routes included in tutorial - Add more pages to better section the content - Pass lesson titles to Lesson.vue - Add content on traditional location-based addressing

Improve lesson page formatting

80d7f11

- Center content to match rest of site - Put the question link in a new footer - Other layout tweaks

Deal with multi-word tutorial shortnames

4d29bff

- Move `issueUrl` from `data` to `computed` in `Lesson.vue` and make it return a string with spaces instead of dashes (Eg "Data structures") - This also fixes the titles of issues opened by clicking the question link in the footer

Edit content of data structures tutorial

7f8db15

- Update data structures tutorial to be more beginner-friendly

Fix invisible button

ad4286d

- Fix a typo that was making the submit button invisible

terichadbourne added 2 commits December 20, 2018 17:21

Make next button mark exerciseless lesson complete

5339688

- If there's no exercise, the next or more tutorials buttons will mark the lesson complete

terichadbourne assigned mikeal and unassigned mikeal Jan 2, 2019

terichadbourne changed the title ~~[WIP] Data-structures tutorial~~ [WIP] Data-structures tutorial (closes #57 Jan 2, 2019

terichadbourne changed the title ~~[WIP] Data-structures tutorial (closes #57~~ [WIP] Data-structures tutorial (closes #57) Jan 2, 2019

This was referenced Jan 2, 2019

Fix lesson component to better match new site design #107

Closed

Make the relationships & terminology around tutorials and lessons more clear #97

Open